Agent .md files with invalid YAML frontmatter are silently skipped without warning #45876

Activity

1. github-actions

   assigned

   nexxeln

   on Aug 28, 2026
2. iceteaSA commented on Oct 22, 2026

   

   iceteaSA

   on Oct 22, 2026

   More actions

   This continues to occur on OpenCode 2.1.1 and on dev at 27cdf5fb. The V2 code is in packages/core, and it has the same silent returns:

   • ConfigMarkdown.parse retries with sanitize when YAML parsing fails. If the retry also throws, parseOption returns undefined (markdown.ts#L16-L22).
   • The agent loader then returns undefined with no log (agent.ts#L176-L178). It does the same when the schema decode fails (agent.ts#L193-L202).
   • The command loader has the same two silent returns (command.ts#L170-L174).
   • Skill files record the cause, but only at debug level (skill.ts#L128-L135).

   A duplicate key is one more cause. gray-matter 4.0.3 throws duplicated mapping key, and sanitize does not change duplicate keys, so the retry also throws. For example, this file does not load and the log has no entry for it:

   ---
   description: Test agent
   mode: subagent
   mode: primary
   ---
   Reply with OK.

   We found this when four agent files were missing from the agent list on 2.1.1. Each file had one key two times in its frontmatter, and nothing showed which files were missing or why. A warn log entry that names the file and the parse or schema error can show this.
3. opencodejr commented on Oct 28, 2026

   

   opencodejrBot

   on Oct 28, 2026

   Contributor

   More actions

   Thanks for the report. I reproduced this on 2.2.0, and it still happens on the latest dev (506ac20c).

   What I did:

   1. In a fresh project, added three files to .opencode/agents/: a valid good.md, badindent.md with the mis-indented frontmatter from your report, and dupkey.md with mode: set twice (the example from the comment above).
   2. Ran opencode debug agents --standalone --log-level debug --print-logs.
   3. Only good is listed. The other two are missing, and no log line mentions either file, even at debug level.

   The same loader does log a warning when an agent uses unsupported fields, but a file that fails to parse is dropped silently. The script below reproduces it on the release and from source.

   Related:

   • agent: frontmatter description starting with '[' silently drops the agent (AgentNotFoundError) #54200: one specific cause of the same silent drop (a description starting with [)
   • commands: unresolvable model in frontmatter silently drops the command #52065: commands are dropped silently in a similar way

   Reproduction script (repro.sh)

   #!/usr/bin/env bash
   # Repro for #45876: agent .md files with invalid YAML frontmatter are dropped silently.
   # Usage: ./repro.sh            -> uses `opencode` from PATH
   #        OC_DEV=/path/to/repo ./repro.sh -> runs CLI from a source checkout
   set -u
   P=$(mktemp -d /tmp/opencode/agentrepro.XXXX)
   export HOME="$P/home" XDG_CONFIG_HOME="$P/home/.config" XDG_DATA_HOME="$P/home/.local/share" XDG_STATE_HOME="$P/home/.local/state" XDG_CACHE_HOME="$P/home/.cache"
   mkdir -p "$HOME" "$P/proj/.opencode/agents"
   cd "$P/proj" && git init -q
   
   # good agent (control)
   cat > .opencode/agents/good.md <<'EOF'
   ---
   description: good agent
   mode: subagent
   ---
   You are fine.
   EOF
   # bad indentation
   cat > .opencode/agents/badindent.md <<'EOF'
   ---
    name: test
     description: test agent
   ---
   
   You are a helpful assistant.
   EOF
   # duplicated key
   cat > .opencode/agents/dupkey.md <<'EOF'
   ---
   description: Test agent
   mode: subagent
   mode: primary
   ---
   Reply with OK.
   EOF
   
   if [ -n "${OC_DEV:-}" ]; then
     oc() { bun --conditions=browser --preload="$OC_DEV/packages/tui/node_modules/@opentui/solid/scripts/preload.js" "$OC_DEV/packages/cli/src/index.ts" "$@"; }
   else
     oc() { opencode "$@"; }
   fi
   oc --version
   echo "=== debug agents (stdout+stderr, log-level debug, print-logs) ==="
   if [ -n "${OC_DEV:-}" ]; then
     # --standalone re-spawns without the preload from source, so run a server explicitly
     export OPENCODE_PASSWORD=repro
     oc serve --port 4611 --log-level debug --print-logs > "$P/out.txt" 2>&1 & SRV=$!
     sleep 12
     oc debug agents --server http://127.0.0.1:4611 >> "$P/out.txt" 2>&1
     echo "exit: $?"; kill $SRV
   else
     oc debug agents --standalone --log-level debug --print-logs > "$P/out.txt" 2>&1
     echo "exit: $?"
   fi
   echo "--- agent ids in output:"
   grep -oE '\b(good|badindent|dupkey)\b' "$P/out.txt" | sort | uniq -c
   echo "--- any log line mentioning the bad files:"
   grep -nE 'badindent|dupkey' "$P/out.txt" || echo "(none)"
   echo "--- warnings/errors in output:"
   grep -niE 'warn|error|yaml|frontmatter' "$P/out.txt" | head -20 || true
   echo "full output: $P/out.txt"

   Run it: bash repro.sh
4. opencodejr

   added

   reproduced

   on Oct 28, 2026
5. Tarquinen

   closed this as completedin #62464on Nov 7, 2026