Troubleshooting - AgentMark Docs

Common errors you may encounter when using AgentMark and how to resolve them. Search your logs for the exact error string.

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

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:

Start the dev server in a separate terminal:
```
agentmark dev
```
Verify it’s reachable at http://localhost:9418.

If using a custom port:

agentmark dev --api-port 9500

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:

In the AgentMark Dashboard, open Settings → API Keys and verify the key.
Make sure the app ID matches the key’s scope (keys are app-scoped).

Update your .env:

AGENTMARK_API_KEY=sk_agentmark_...
AGENTMARK_APP_ID=app_...

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

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

{
  "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) and merge its tools into the model call. See 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:

agentmark build --out dist/agentmark

Then make sure your FileLoader points at the same directory:

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:

{
  "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:

# 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 <Tag> has its closing </Tag>. See 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:

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:

{"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<AgentMarkTypes>(), TS flags prop shape mismatches. The generated types reflect the prompt’s input_schema frontmatter, so regenerate after editing:

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:

npm install -g @agentmark-ai/cli
agentmark dev

2. Use the local pin. A project scaffolded by agentmark init 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:

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

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:

agentmark dev --api-port 9500

# or find and kill the holder
lsof -i :9418
kill -9 <PID>

Disable CLI update banner

Set AGENTMARK_NO_UPDATE_NOTIFIER=1 in your environment to suppress the version-upgrade banner.

Still having issues?

Update your packages to the latest version:

npm update @agentmark-ai/cli @agentmark-ai/prompt-core @agentmark-ai/sdk

Open an issue on GitHub with the exact error string, your SDK version, and a minimal reproduction.

Have questions?

Reach out any time:

Email the team at hello@agentmark.co for support
Schedule an Enterprise Demo to learn about AgentMark’s business solutions

​Connection and authentication

​Can’t connect to local dev server

​Not authorized (401)

​Traces

​No traces, or traces missing the model span

​Models

​Model not resolved at your call site

​MCP servers

​MCP server not registered

​Prompts and files

​File not found

​Pre-built prompt not found

​agentmarkPath / breaks build

​Invalid YAML frontmatter

​Unterminated TemplateDX expression

​Datasets and experiments

​Dataset file not found

​Invalid JSONL

​Types

​Props don’t match prompt input

​CLI

​agentmark command not found

​Port already in use

​Disable CLI update banner

​Still having issues?

​Have questions?

Connection and authentication

Can’t connect to local dev server

Not authorized (401)

Traces

No traces, or traces missing the model span

Models

Model not resolved at your call site

MCP servers

MCP server not registered

Prompts and files

File not found

Pre-built prompt not found

agentmarkPath `/` breaks build

Invalid YAML frontmatter

Unterminated TemplateDX expression

Datasets and experiments

Dataset file not found

Invalid JSONL

Types

Props don’t match prompt input

CLI

`agentmark` command not found

Port already in use

Disable CLI update banner

Still having issues?

Have questions?