Troubleshoot activation failures
Identify the failing activation seam, apply the documented recovery, and verify the configuration after reload.
Start with the first Vector or OpenCode error from the activation. Correct that owning seam, reload OpenCode, and invoke a known command from the Vector Configuration.
The entrypoint does not load
Check that the configured URL is absolute, uses file://, and points to a module whose default export is the OpenCode Plugin Entrypoint. For a package install, verify the project-local re-export and the package’s built ESM export.
After correction, reload OpenCode and confirm a known command such as /project-summary is available.
Context resolution fails at agent.list()
Vector could not resolve the active location through the pinned host operation. Reload OpenCode and try again. If the failure remains, verify that the OpenCode version matches the packages pinned by Vector.
Runtime Configuration fails
Read, JSON parse, and schema failures name the affected source and path without including raw configuration contents. Correct the named file, JSON value, or Configuration Author-owned schema, then reload OpenCode.
An invalid runtimeConfig.slug throws when the builder is created. Use lowercase ASCII letters and digits separated by single hyphens, then reload the corrected entrypoint.
computeContext fails
Return a synchronous plain object without runtimeConfig, cwd, or project. Do not return arrays, dates, class instances, promises, or values with a callable then property. Correct thrown property getters as well as the callback body.
This failure occurs before the configuration callback, extension materialization, or host registration. Reload OpenCode after correction.
Extension building fails
A thrown value from the Vector Configuration or an extension build(context) callback stops activation. Correct the named callback. Vector preserves an Error; a non-Error thrown value receives a safe boundary message.
Instruction File resolution fails
Use one absolute or ~/ string path, or one file: URL object, for each instructionFiles entry. Remove relative paths, URL strings, globs, and non-file URL objects. Check that the selected local file exists, resolves through any symlink to a readable regular file, and remains readable as UTF-8. The error names the selected source and whether validation, URL conversion, canonicalization, inspection, or reading failed.
Correct instructionFiles, then reload OpenCode. Vector resolves every Instruction File before registering any host transform.
External Skill resolution fails
For a Local Skill, use the exact skill directory as an absolute or ~/ path. Check that the symlink target is readable, its canonical basename equals the definition id, and SKILL.md begins with valid YAML frontmatter. The frontmatter needs an exact matching string name and a non-empty string description. Top-level slash must be boolean. Namespaced opencode/slash and opencode/autoinvoke metadata accept booleans or trimmed true and false strings; top-level autoinvoke is ignored.
For a Managed Skill, remove local or file: sources, URL credentials or query parameters, and embedded #ref or @skill selectors. Put a Git ref in external.ref only when source is a remote Git source; refs do not apply to skills.sh, direct skill files, or archives. Vector supplies the definition id as the selected skill. Check ambient Git or SSH access to a Git source when installation fails.
A valid when-missing cache entry is reused. An invalid entry is repaired under the shared lock. An always update must succeed even when an older cache remains. Correct the source, filesystem permission, frontmatter, or manager failure, then reload OpenCode. Vector does not prune or watch the cache.
Snapshot preflight fails
Correct the duplicate identity, missing related extension, or invalid default named by the error. Preflight examines the complete Snapshot and fails before any host transform is registered.
Host registration fails
Registration stops at the failing host operation. Earlier transforms may remain because registration is sequential and non-atomic. Correct the host failure, reload OpenCode, and verify every extension domain selected by the configuration.
Read Lifecycle for the ordering behind these symptoms and Extensions for the External Skill definition shapes.