Skip to main content
Version: 0.9.1

Troubleshooting

Use this page when installs fail, configs do not validate, or MCP servers do not connect. Most issues are configuration or PATH-related, so start with a quick triage before diving deeper. The goal is to get you back to a predictable state without guessing.

Quick triage:

  • Run al doctor and read the warnings.
  • Confirm al --version works in the repo.
  • If you recently edited .agent-layer/, run al sync to refresh generated client outputs.
  • If you are offline or locked down, set AL_NO_NETWORK=1 to silence update checks.

In this page​

Note: the MCP server issues section includes fallback guidance for both Codex and Claude in VS Code.

If the triage does not resolve it, use the sections below.

Install issues​

If you have not installed al yet, start with /install.

al not on PATH​

  • Verify install location:
    • Homebrew: brew --prefix conn-castle/tap/agent-layer
    • Script installs to a standard location for your OS
  • Open a new terminal after install so your PATH refreshes.
  • Run which al or command -v al to confirm it resolves.

Missing client CLI​

Agent Layer does not install Gemini, Claude, Codex, VS Code, or Antigravity. Install the target client and ensure it is on your PATH.

VS Code preflight: code command not found​

al vscode and repo-local launchers require the code command on PATH.

  • macOS: Command Palette -> Shell Command: Install 'code' command in PATH
  • Linux: Command Palette -> Shell Command: Install 'code' command in PATH
  • Re-open your terminal and confirm with command -v code

VS Code preflight: managed settings block conflict​

If launch fails with a managed-block conflict in .vscode/settings.json, Agent Layer detected duplicate/misaligned marker boundaries for its managed block.

Fix:

  1. Run al sync to rewrite the managed block.
  2. If conflict remains, remove duplicate // >>> agent-layer / // <<< agent-layer markers in .vscode/settings.json.
  3. Re-run al vscode.

Update checks fail in locked-down environments​

al init and al doctor may warn if update checks are blocked by your network. This does not prevent normal use. Set AL_NO_NETWORK=1 to disable update checks and downloads.

Configuration errors​

"agent layer isn't initialized"​

Run al init in the repo to create .agent-layer/ and docs/agent-layer/.

Generated files showing up in git​

Generated client outputs are meant to be disposable. If you see generated files like .agent/skills/, .gemini/settings.json, .claude/settings.json, .codex/, .vscode/mcp.json, .vscode/prompts/, .vscode/settings.json, .mcp.json, .github/copilot-instructions.md, AGENTS.md, CLAUDE.md, or GEMINI.md showing up in git status, it usually means one of:

  • the repo has not been initialized with Agent Layer's managed .gitignore block,
  • the ignore rules were customized,
  • or the generated files were committed previously.

Run al sync (or al <client>) to reinstall the managed ignore rules. If the files were already committed, you will also need to stop tracking them in git (and ensure .agent-layer/.env stays untracked, since it contains secrets).

caution

.codex/config.toml may contain resolved values for MCP server URLs, commands, or environment variables. Treat it as private and keep it gitignored.

"gitignore block must not include managed markers or template hash"​

.agent-layer/gitignore.block should contain only ignore patterns and comments. Agent Layer injects the managed header and template hash only when updating the root .gitignore. If your template file contains # >>> agent-layer, # <<< agent-layer, or # Template hash: ..., run:

al upgrade repair-gitignore-block
al sync

"invalid pinned version" or version format errors​

.agent-layer/al.version must be X.Y.Z or vX.Y.Z.

Parser behavior:

  • blank lines and # comments are ignored
  • exactly one non-comment version line is expected
  • empty/invalid/multi-version pin files produce a warning and fall back to the current CLI version

Fix the file or run al upgrade to rewrite it to the current version. See Version pinning and Upgrades.

config.toml validation failures​

Common causes:

  • missing enabled fields for agents or MCP servers
  • invalid approvals.mode value
  • transport not set to http or stdio
  • mixing url with command in the same MCP server

Run al doctor to see structured config errors.

VS Code settings disappear after sync​

Some VS Code extensions (for example Peacock) write settings through the VS Code configuration API in a way that can land inside the Agent Layer-managed block in .vscode/settings.json.

If that happens, Agent Layer replaces the managed block on the next al sync, so extension-written settings inside that block are removed.

Fix:

  1. Manually edit .vscode/settings.json and move extension-owned settings outside the managed marker block (// >>> agent-layer to // <<< agent-layer).
  2. If the managed block is currently the last block in the file, add a user-owned tail anchor key after it:
{
  // >>> agent-layer
  // ... Agent Layer managed settings ...
  // <<< agent-layer
  "__settingsTailAnchor": 0
}

This creates a stable non-managed tail position for extension writes.

MCP server issues​

MCP server fails to start​

  • Check that the command exists on your PATH (for example npx or uvx).
  • On macOS, install Node via Homebrew (brew install node) so VS Code can find node and npx. Avoid per-user installs that only exist in shell profiles.
  • Verify any required secrets in .agent-layer/.env.
  • For HTTP servers, confirm the URL and headers are correct.
  • Use al doctor to confirm discovery and tool listing.

Global MCP server fallback for VS Code (Codex)​

This is primarily a VS Code fallback.

Continue using al codex on the CLI. al codex sets a repo-local CODEX_HOME, so Codex uses the repo-local .codex/config.toml (which Agent Layer generates from .agent-layer/config.toml, including MCP servers).

If you launch VS Code without Agent Layer's repo-local launcher, the Codex VS Code extension will not receive the repo-local CODEX_HOME. In that case, the extension continues to use repo-local instructions and skills, but it uses MCP servers from your global Codex config instead.

Tradeoffs (VS Code without launcher):

  • You are no longer using .agent-layer/config.toml as the single source of truth for Codex MCP servers.
  • Codex auth/state is shared across repos (which can be convenient, but is less isolated).

Workflow (best-effort; depends on your Codex client version):

  1. Configure MCP servers in your global Codex config (typically ~/.codex/config.toml).

    Example (no secrets):

    [mcp_servers.ripgrep]
    command = "npx"
    args = ["-y", "mcp-ripgrep@0.4.0"]

    [mcp_servers.fetch]
    command = "uvx"
    args = ["mcp-server-fetch==2025.4.7"]

    Note: for servers that require API keys, prefer environment variables and avoid hardcoding secrets into your global config. If you intentionally prefer floating dependencies, switch to @latest/unpinned args explicitly.

  2. Launch VS Code without Agent Layer's CODEX_HOME launcher so the extension uses the global config.

  3. Keep using Agent Layer for repo-local prompts and skills.

If you want the fully managed setup in VS Code, use al vscode (or the generated open-vscode launcher) so VS Code starts with the repo-local CODEX_HOME and uses MCP servers projected from .agent-layer/config.toml.

Global config fallback for VS Code (Claude)​

This is primarily a VS Code fallback, and applies only when local_config_dir = true is set under [agents.claude].

When local_config_dir is enabled, al claude sets a repo-local CLAUDE_CONFIG_DIR, so Claude Code uses the repo-local .claude-config/ for user-level configuration (settings and caches). For al vscode, CLAUDE_CONFIG_DIR is set only when both local_config_dir is true and [agents.claude_vscode] is enabled.

Known upstream limitation

Claude Code currently stores OAuth/auth credentials in the OS credential store (macOS Keychain service "Claude Code-credentials"; Linux libsecret/gnome-keyring) regardless of CLAUDE_CONFIG_DIR. This means local_config_dir isolates settings and caches but not authentication. Per-repo login isolation does not work until this is fixed upstream. This has been reported to the Claude Code team.

If you launch VS Code without Agent Layer's repo-local launcher, the Claude extension will not receive the repo-local CLAUDE_CONFIG_DIR. In that case, the extension uses your global ~/.claude/ configuration, so settings are shared across repositories.

When local_config_dir is disabled (the default), Claude always uses the global ~/.claude/ configuration regardless of how VS Code is launched.

Tradeoffs (VS Code without launcher, with local_config_dir enabled):

  • Claude settings and caches are shared across repositories (which can be convenient, but is less isolated).
  • Auth is always shared across repositories due to the upstream limitation above.

If you want the fully managed setup in VS Code with local_config_dir enabled, use al vscode (or the generated open-vscode launcher) so VS Code starts with the repo-local CLAUDE_CONFIG_DIR.

Gemini trust warning: trustedFolders.json​

When Gemini is enabled, al sync attempts to add the repo path to ~/.gemini/trustedFolders.json so Gemini CLI can load repo-local .gemini/settings.json.

If this write fails, sync still completes and emits a non-fatal warning. Common causes are missing home-directory permissions or a corrupt trustedFolders.json file.

Fix:

  1. In Gemini CLI, trust the workspace via /permissions.
  2. Or manually add your repo path to ~/.gemini/trustedFolders.json.
  3. Re-run al sync and verify the warning is gone.

Client CLI not found​

Install the target client CLI (Gemini, Claude, Codex, VS Code, Antigravity) and ensure it is available on your PATH.

Pinning and offline mode​

For upgrade-policy guarantees and migration expectations, see Upgrades.

"version is not cached" when offline​

If AL_NO_NETWORK=1 is set and the pinned version is not cached, al cannot download the version. Temporarily unset AL_NO_NETWORK or pre-populate the cache:

al upgrade prefetch --version X.Y.Z

Still stuck​

Run al doctor and read the warnings. It will surface missing secrets, invalid config, and MCP connectivity issues.

If you still cannot get unstuck, open a GitHub issue and include the details below:

If you are not sure whether it is a bug or “just usage,” it is still fine to file an issue. Clear reproduction details are more valuable than perfect categorization.

Include:

  • your al --version
  • the output of al doctor (redact secrets)
  • your .agent-layer/config.toml (redact secrets and private URLs as needed)
note

If you run al doctor with no MCP servers enabled, it will still validate config and instructions.