---
title: Troubleshooting
description: Fix common install, configuration, and MCP server issues.
sidebar_position: 5
---

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`](./reference#doctor) and read the warnings.
- Confirm `al --version` works in the repo.
- If you recently edited `.agent-layer/`, run [`al sync`](./reference#sync) to refresh generated client outputs.
- If you are offline or locked down, set [`AL_NO_NETWORK=1`](./reference#environment-variables) to silence update checks.

## In this page

- [Install issues](#install-issues)
- [Configuration errors](#configuration-errors)
- [MCP server issues](#mcp-server-issues)
- [Pinning and offline mode](#pinning-and-offline-mode)
- [Still stuck](#still-stuck)

Note: the MCP server issues section includes fallback guidance for both [Codex](#global-mcp-server-fallback-for-vs-code-codex) and [Claude](#global-config-fallback-for-vs-code-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](/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 Antigravity, Claude, Codex, Copilot CLI, or VS Code. 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`](./reference#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 `.agents/skills/`, `.agy/`, `.antigravitycli/`, `.claude/settings.json`, `.claude/skills/`, `.codex/`, `.copilot/`, `.vscode/mcp.json`, `.vscode/settings.json`, `.mcp.json`, `.github/copilot-instructions.md`, `AGENTS.md`, or `CLAUDE.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:

```bash
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](./concepts#version-pinning) and [Upgrades](./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:

```jsonc
{
  // >>> 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 the current repo trust stanza and 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):

   ```toml
   [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.

:::caution 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`.

### Antigravity MCP probe shows runtime discovery disabled

Agent Layer writes Antigravity MCP config to `.agy/antigravity-cli/mcp_config.json`. `agy` v1.0.0 migrates that file into its internal config directory, but the current observed baseline does not register MCP servers at runtime.

Check your installed `agy` behavior:

```bash
al probe agy
```

If `mcp_runtime_discovery` is still false, the generated config exists but Antigravity will not expose those MCP tools yet.

### `al agy` fails to launch or `agy` is not found

If `al agy` exits with `antigravity launcher requires \`agy\` on PATH`, install Antigravity from [antigravity.google](https://antigravity.google) and ensure the `agy` binary is on your `PATH`. Run `al probe agy` as a single-step diagnostic: it confirms `agy` is discoverable, captures the version, and reports the observed capability matrix. The probe writes a forensic workspace under `.agent-layer/tmp/probe-antigravity-<ts>-<suffix>/` which you can attach to a bug report; `al upgrade --apply-tmp-deletions` cleans these up.

### Client CLI not found

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

## Pinning and offline mode

For upgrade-policy guarantees and migration expectations, see [Upgrades](./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:

```bash
al upgrade prefetch --version X.Y.Z
```

## Still stuck

Run [`al doctor`](./reference#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:

- [GitHub Issues](https://github.com/conn-castle/agent-layer/issues)

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.
:::
