Custom slash commands can crash opencode on startup

[steinmann321]

Description

Custom slash commands (markdown) containing YAML-like instructions crash opencode on startup

Workaround: Quote the value to make it a proper YAML string or add a > and a linebreak.

OpenCode version

0.15.19

Steps to reproduce

1. create a project local slash command in .opencode/command/crash-me.md
2. add this to crash-me.md:

---
argument-hint: [title] [short description] [logs or ticket number if applicable]
description: Create a bug issue
---

- This is an example how to crash opencode with YAML-style (kind of) instructions

3. run opencode: opencode ~/projects/test-opencode
4. opencode crashes with

YAMLException {
  name: "YAMLException",
  reason: "can not read an implicit mapping pair; a colon is missed",
  mark: Mark {
    name: null,
    buffer: "\nargument-hint: [title] [short description] [logs or ticket number if applicable]\ndescription: Create a bug issue\n\u0000",
    position: 44,
    line: 1,
    column: 43,
    getSnippet: [Function: getSnippet],
    toString: [Function: toString],
  },
  message: "can not read an implicit mapping pair; a colon is missed at line 2, column 44:\n     ... nt: [title] [short description] [logs or ticket number if applic ... \n                                         ^",
  originalLine: 14198,
  originalColumn: 29,
  stack: "Error\n    at generateError (../../node_modules/.bun/[email protected]/node_modules/js-yaml/lib/js-yaml/loader.js:167:14)\n    at throwError (../../node_modules/.bun/[email protected]/node_modules/js-yaml/lib/js-yaml/loader.js:173:9)\n    at readBlockMapping (../../node_modules/.bun/[email protected]/node_modules/js-yaml/lib/js-yaml/loader.js:1064:11)\n    at composeNode (../../node_modules/.bun/[email protected]/node_modules/js-yaml/lib/js-yaml/loader.js:1359:12)\n    at readDocument (../../node_modules/.bun/[email protected]/node_modules/js-yaml/lib/js-yaml/loader.js:1525:3)\n    at loadDocuments (../../node_modules/.bun/[email protected]/node_modules/js-yaml/lib/js-yaml/loader.js:1588:5)\n    at load (../../node_modules/.bun/[email protected]/node_modules/js-yaml/lib/js-yaml/loader.js:1614:19)\n    at parseMatter (../../node_modules/.bun/[email protected]/node_modules/gray-matter/index.js:109:17)\n    at loadCommand (src/config/config.ts:166:18)\n    at processTicksAndRejections (native:7:39)",
  toString: [Function: toString],
}

Verify with:

1. delete the file
2. run opencode ~/projects/test-opencode without issues

Screenshot and/or share link

No response

Operating System

macOS 26.0.1

Terminal

iTerm2

[github-actions[bot]]

This issue might be a duplicate of existing issues. Please check:

• #3461: Agent frontmatter parsing issues where YAML frontmatter in markdown files causes problems with special characters and parsing
• #2460/#2461: Model field in slash commands being ignored due to frontmatter parsing issues
• #3203: Model specified in .md file is ignored - similar frontmatter parsing problems

Feel free to ignore if none of these address your specific case.

[rekram1-node]

~~You are providing invalid yaml and getting an error, I don't think this is a bug?~~

[taqtiqa-mark]

You are providing invalid yaml and getting an error, I don't think this is a bug?

I believe the crash behavior is the bug. Generally, the error should be reported in a way the user understands how to resolve the error, and if required, OC closes gracefully?

[rekram1-node]

Maybe we should show the error better but it isnt a crash this is a validation error when u start opencode and it is expected

[steinmann321]

This crash is completely unexpected from my point of view. All other agents I use (RooCode, ClaudeCode, codex, gemini CLI) can parse the same command file without any problem.

And even if opencode is more strict here it should not crash this way. It should run and just not load the command and maybe notify the user on this. This would make me able to fix it with opencode itself.

[rekram1-node]

Generally for user configs we like to error immediately to show you that something is wrong

[taqtiqa-mark]

@rekram1-node; Are you able to keep OC running after the "error", or does it crash?

[rekram1-node]

You can't run it with an invalid config that's intentional, I suppose since the error isn't being handled in the same manner as other config errors, u can say it is a "crash" but when a configuration is invalid we exit haha

I will make the error prettier, but we do the same behavior if your opencode.json contains unexpected keys, or if you put files in incorrect directories

[taqtiqa-mark]

I think @steinmann321 has a valid point. This is a dev tool, and a dev tool on the bleeding edge of some technologies (AI programs) that are flaky, idiosyncratic and temperamental.

But most importantly, it is tool to collab with those programs to develop OpenCode itself....

u can say it is a "crash" but when a configuration is invalid we exit haha

... this means doing everything to try to "stay in the game", not taking your bat and ball, going home sneering haha, because some AI produced a comma you don't like....

[rekram1-node]

Oh Im not sneering at all I was just trying to stay in good fun and say u do have a point about it being a crash since it isnt gracefully handled like the other errors in config I put haha because the previous point I made was partially incorrect

Apologies for any miscommunication

[rekram1-node]

I will start by making this a named error that we handle better so it is at the very least more actionable and less messy, and after I will check out how other people are handling it, maybe they do something we aren't

Edit in next release:

[greeze]

I want to reiterate the point that failing on startup because of an invalid custom slash-command (and in my case just today after an update, a custom agent) prevents us from using OpenCode to solve the problem.

If deleting the custom command allows the application to launch, then clearly that command is not a prerequisite for launch. The application should ignore the invalid file, alert the user to the issue, and complete its launch so the user can use OpenCode to solve this problem.

The current situation forces users back to other tools (which don't fail on startup due to non-critical invalid custom commands) in order to fix a problem in OpenCode. It would be nice if users could feel confident in uninstalling those other TUIs, but this approach of failing to launch when encountering non-critical errors prevents that.

[rekram1-node]

yep totally fair point we should fix this