---
title: Troubleshoot activation failures
description: Identify the failing activation seam, apply the documented recovery, and verify the configuration after reload.
sidebar:
  label: Troubleshoot
---

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](/activate/lifecycle) for the ordering behind these symptoms and [Extensions](/api/extensions) for the External Skill definition shapes.