> ## Documentation Index > Fetch the complete documentation index at: https://puzzlet-9ba7bb98.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Solutions to common errors and issues when using AgentMark Common errors you may encounter when using AgentMark and how to resolve them. Search your logs for the exact error string. Run [`agentmark doctor`](/reference/cli-commands#agentmark-doctor) first. It statically checks your config, prompts, client, and dependencies and points you at the fix for most setup problems before you start grepping logs. Traces not showing up? Those are usually silent failures with no error string, so they have their own page: [Troubleshooting traces](/observe/troubleshooting). ## Connection and authentication ### Can't connect to local dev server **Error** (from Node fetch): `TypeError: fetch failed`, with a cause containing `ECONNREFUSED` and the dev-server port (for example `connect ECONNREFUSED 127.0.0.1:9418`). The exact cause rendering varies by Node version. **Cause:** The local dev server isn't running on the port your `ApiLoader.local()` is pointing at. **Solution:** 1. Start the dev server in a separate terminal: ```bash theme={null} agentmark dev ``` 2. Verify it's reachable at `http://localhost:9418`. 3. If using a custom port: ```bash theme={null} agentmark dev --api-port 9500 ``` ```typescript theme={null} ApiLoader.local({ baseUrl: "http://localhost:9500" }) ``` ### Not authorized (401) **Error** (gateway response, HTTP status 401): `{"error":{"message":"Not authorized"}}` **Cause:** Your `AGENTMARK_API_KEY` is missing, revoked, or doesn't match the `X-Agentmark-App-Id` / `AGENTMARK_APP_ID` you sent. **Solution:** 1. In the [AgentMark Dashboard](https://app.agentmark.co), open **Settings → API Keys** and verify the key. 2. Make sure the app ID matches the key's scope (keys are app-scoped). 3. Update your `.env`: ```bash theme={null} AGENTMARK_API_KEY=sk_agentmark_... AGENTMARK_APP_ID=app_... ``` 4. Restart your application so it picks up the new values. ## Traces ### No traces, or traces missing the model span A silent failure (no error string): the app runs, but spans don't arrive, or the model/generation span is missing while custom spans show up. Causes include a missing `registerGlobally: true`, telemetry not enabled on the AI SDK call, env vars not loaded when the process started, or a short-lived script exiting before the batch flushes. See [Troubleshooting traces](/observe/troubleshooting) for the symptom-by-symptom fixes. ## Models ### Model not resolved at your call site **Symptom:** A run fails with a provider error like `model not found` or `Unknown model`, even though you set the model name in your prompt frontmatter. **Cause:** The AgentMark client renders prompts to a neutral shape; it doesn't resolve models. After you format a prompt, `text_config.model_name` (or `object_config.model_name`) is the raw string from frontmatter (for example `openai/gpt-5`). Mapping that string to a provider model happens in **your SDK call or [executor](/getting-started/client-setup#connect-your-sdk)**. If that mapping is missing or passes the prefixed string straight through, the provider rejects it. **Solution:** Map `model_name` to a provider model where you call the model. For example, with the Vercel AI SDK: ```typescript theme={null} import { client } from "./agentmark.client"; import { openai } from "@ai-sdk/openai"; import { generateText } from "ai"; const prompt = await client.loadTextPrompt("greeting.prompt.mdx"); const { messages, text_config } = await prompt.format({ props: { name: "Alice" } }); // Strip the "openai/" prefix before handing the name to the provider. const result = await generateText({ model: openai(text_config.model_name.replace(/^openai\//, "")), messages, }); ``` See [Connect your SDK](/getting-started/client-setup#connect-your-sdk) for copy-paste model mappings (Vercel AI SDK, raw OpenAI, raw Anthropic, agent frameworks) in both TypeScript and Python. ## MCP servers ### MCP server not registered **Error** (from `@agentmark-ai/prompt-core`): `MCP server 'docs' not registered. Available servers: ...` **Cause:** A prompt references `mcp://docs/...`, but you haven't declared a server named `docs` in `agentmark.json`. The neutral render surfaces the tool names a prompt requests; it doesn't connect the server. **Solution:** Declare the server by name in `agentmark.json` so it resolves and appears in the Dashboard editor: ```json theme={null} { "mcpServers": { "docs": { "url": "https://example.com/mcp" } } } ``` Then connect the server at your call site (with your SDK's MCP client, or inside an [executor](/getting-started/client-setup#connect-your-sdk)) and merge its tools into the model call. See [Connect the server at your call site](/build/mcp#3-connect-the-server-at-your-call-site). ## Prompts and files ### File not found **Error** (CLI run-prompt): `File not found: /absolute/path/to/prompt.prompt.mdx` **Cause:** The path passed to `run-prompt` doesn't resolve to an existing file. **Solution:** Pass a path relative to your project root (for example `agentmark/greeting.prompt.mdx`). ### Pre-built prompt not found **Error** (FileLoader): `Pre-built prompt not found: agentmark/greeting.prompt.json. Run 'agentmark build' to compile your prompts.` **Cause:** `FileLoader` reads compiled JSON from the `--out` directory of `agentmark build`. Either you haven't built the prompt yet, or the output directory doesn't match. **Solution:** ```bash theme={null} agentmark build --out dist/agentmark ``` Then make sure your `FileLoader` points at the same directory: ```typescript theme={null} const loader = new FileLoader("./dist/agentmark"); ``` ### agentmarkPath `/` breaks build **Error:** `AgentMark directory not found: /agentmark. Check your agentmark.json configuration.` **Cause:** `"agentmarkPath": "/"` in `agentmark.json` resolves to the filesystem root. The scaffolder writes `"."`, the relative path from the project root. **Solution:** Change `agentmark.json`: ```json theme={null} { "agentmarkPath": "." } ``` ### Invalid YAML frontmatter **Error** (from the YAML parser): `end of the stream or a document separator is expected (2:12)`. Line and column vary by the issue. **Cause:** Frontmatter YAML syntax error: a missing space after `:`, incorrect indentation, or unquoted strings with special characters. **Solution:** ```yaml theme={null} # Wrong — no space after colon model_name:gpt-5 # Right model_name: gpt-5 # Wrong — lost indentation under the parent key text_config: model_name: gpt-5 # Right text_config: model_name: gpt-5 ``` ### Unterminated TemplateDX expression **Error**: `Unexpected end of file in expression, expected a corresponding closing brace for '{'` **Cause:** An open `{` or tag without its matching close. **Solution:** Verify every `{expression}` has a closing `}` and every `` has its closing ``. See [TemplateDX syntax](/templatedx/syntax). ## Datasets and experiments ### Dataset file not found Check that the `dataset:` path in your prompt's `test_settings` resolves from the prompt file's directory: ```yaml theme={null} test_settings: dataset: ./datasets/test.jsonl ``` If the file exists but the path is wrong, the error surfaces as `ENOENT` from Node's `fs.createReadStream`. The fix is to correct the relative path. ### Invalid JSONL Each line must be a complete JSON object: ```jsonl theme={null} {"input": {"name": "Alice"}, "expected_output": "Hello Alice"} {"input": {"name": "Bob"}, "expected_output": "Hello Bob"} ``` Validate with `cat dataset.jsonl | jq -c '.'`. Any line it can't parse is the broken one. ## Types ### Props don't match prompt input When you type `createAgentMark()`, TS flags prop shape mismatches. The generated types reflect the prompt's `input_schema` frontmatter, so regenerate after editing: ```bash theme={null} agentmark generate-types --root-dir ./agentmark > agentmark.types.ts ``` ## CLI ### `agentmark` command not found **Error:** `command not found: agentmark` The bare `agentmark` command only resolves when the CLI is on your PATH (global install) or run through an npm script (local pin). Pick whichever fits: **1. Install globally** so `agentmark` is always on your PATH: ```bash theme={null} npm install -g @agentmark-ai/cli agentmark dev ``` **2. Use the local pin.** A project scaffolded by [`agentmark init`](/getting-started/quickstart) pins `@agentmark-ai/cli` as a dev dependency and adds npm scripts, so npm resolves the pinned binary from `node_modules/.bin`, no global install needed: ```bash theme={null} npm install # fetch the pinned CLI npm run dev # runs `agentmark dev` via the pinned binary ``` **3. Run without installing**, via `npx` (resolves a local pin if present, otherwise downloads on demand): ```bash theme={null} npx @agentmark-ai/cli dev npx @agentmark-ai/cli run-prompt path/to/prompt.prompt.mdx ``` ### Port already in use **Error:** `EADDRINUSE: address already in use :::9418` **Solution:** Use a different port, or kill the existing process: ```bash theme={null} agentmark dev --api-port 9500 # or find and kill the holder lsof -i :9418 kill -9 ``` ### Disable CLI update banner Set `AGENTMARK_NO_UPDATE_NOTIFIER=1` in your environment to suppress the version-upgrade banner. ## Still having issues? 1. Update your packages to the latest version: ```bash theme={null} npm update @agentmark-ai/cli @agentmark-ai/prompt-core @agentmark-ai/sdk ``` 2. Open an issue on [GitHub](https://github.com/agentmark-ai/agentmark/issues) with the exact error string, your SDK version, and a minimal reproduction.

Have questions?

Reach out any time: