> ## Documentation Index
> Fetch the complete documentation index at: https://cognitio-agent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Find the cause of installation, credentials, tools, streaming, and session problems.

Start with the symptom below. If it is still unclear, send a minimal reproduction to [ugurlu.oozgur@gmail.com](mailto:ugurlu.oozgur@gmail.com) or [open an issue](https://github.com/ozgurugurlu/cognitio-agent-sdk/issues).

## The runtime cannot be found

The local runtime is installed through an optional npm dependency. Confirm the SDK is installed in the project where you run the script:

```sh theme={null}
node --version
npm ls cognitio-agent-sdk
node -p "process.platform + ' ' + process.arch"
```

Use Node.js 22+ and a [supported platform](https://cognitio-agent.mintlify.site/installation.md#supported-local-runtimes). Reinstall with optional dependencies included:

```sh theme={null}
npm install cognitio-agent-sdk@2.0.1 --include=optional
```

Do not copy `node_modules` between operating systems or CPU architectures. In a minimal container without a local runtime, use [remote mode](https://cognitio-agent.mintlify.site/cookbook/remote.md).

## The model rejects my API key

1. Confirm that the key belongs to the provider in `model`. An OpenAI key goes with an `openai/...` model.
2. Load the key in the process that runs the agent. With a `.env` file, use `node --env-file=.env agent.mjs`.
3. Check that your provider account has access to the selected model and available quota. Installing the SDK does not grant provider access.
4. If you use a custom environment-variable name, pass it through `spawn.auth`; see [runtime defaults](https://cognitio-agent.mintlify.site/defaults-and-isolation.md#supply-credentials-explicitly-when-needed).

Check whether a key is present without printing its value:

```sh theme={null}
node --env-file=.env -e 'console.log({ hasOpenAIKey: Boolean(process.env.OPENAI_API_KEY) })'
```

Your personal runtime login files are not automatically used by the isolated SDK runtime. The quickstart uses an explicit provider API key.

## A model or option is unavailable

A model ID has the form `provider/model`. The SDK's typed catalog offers completion; it does not prove that your provider account can use every entry. Verify the provider's model access and use a model you can call.

If an effort or thinking setting is rejected, remove that optional setting first. Model features differ across providers. See [models and prompts](https://cognitio-agent.mintlify.site/concepts/models-and-prompts.md).

## The agent cannot use a tool

Check these in order:

1. **Availability:** use the correct ID from [built-in tools](https://cognitio-agent.mintlify.site/concepts/built-in-tools.md). Some tools depend on the model or runtime configuration.
2. **Selection:** a nonempty `allowedTools` list limits the tool inventory. Custom tools are exposed as `sdk_<name>`.
3. **Denials:** remove the quickstart's `disallowedTools: ["*"]` when enabling tools. An empty `allowedTools` array does not disable tools.
4. **Permissions:** a selected tool may still need approval. Review server permission rules and your `permissionMode`.
5. **Callback:** validate custom tool input inside `execute`; the schema describes the tool but does not replace your validation.

Use [permissions](https://cognitio-agent.mintlify.site/concepts/permissions.md) and the [custom-tool cookbook](https://cognitio-agent.mintlify.site/cookbook/custom-tool.md) for complete examples.

## A run waits for permission

An `ask` decision needs an application that can respond. For unattended jobs, choose a policy that returns concrete allow/deny decisions and rejects unresolved prompts. `canUseTool` handles unresolved approvals, not every tool invocation. A callback timeout can leave a permission request waiting; it is not an automatic denial.

Avoid enabling the interactive `question` tool unless your application implements the corresponding input flow. See [permissions](https://cognitio-agent.mintlify.site/concepts/permissions.md) and [cancellation](https://cognitio-agent.mintlify.site/concepts/streaming.md).

## A run returns an error without throwing

Setup and connection errors can throw. A completed model run can instead return `isError: true` and a terminal `subtype`, such as `error_max_turns` or `error_aborted`. Check both channels:

```ts theme={null}
import { Agent, isSdkError, shutdown } from "cognitio-agent-sdk"

const agent = new Agent({
  model: "openai/gpt-4.1-mini",
  disallowedTools: ["*"],
  maxTurns: 3,
})

try {
  const result = await agent.run("Explain a database index in one sentence.")
  if (result.isError) {
    console.error("Run stopped:", result.subtype)
  } else {
    console.log(result.text)
  }
} catch (error) {
  if (isSdkError(error)) console.error("SDK error:", error.kind, error.message)
  else console.error(error)
} finally {
  await agent.close().finally(() => shutdown())
}
```

Use `kind` for SDK setup/lifecycle errors and `subtype` for terminal run outcomes. See [SdkError](https://cognitio-agent.mintlify.site/api-reference/interfaces/SdkError.md) and [RunResult](https://cognitio-agent.mintlify.site/api-reference/interfaces/RunResult.md).

## Structured output is missing

Check the terminal result before reading structured data. The model must support the required tool/output behavior, the response must fit its output limit, and the `StructuredOutput` tool must remain available. A wildcard tool denylist disables it too.

Use a simple provider-facing schema and validate your application's stronger constraints afterward. The [contact extraction cookbook](https://cognitio-agent.mintlify.site/cookbook/structured-extraction.md) shows the complete pattern.

## The script does not exit

Finish, abort, or return from active streams, and close resources you own. With the default `Agent` or `query()` runtime, call `shutdown()` when the whole application is done. An Agent created with explicit `spawn` options owns its dedicated runtime; a borrowed client must be closed by its creator.

Do not call process-wide `shutdown()` after each request in a shared web service. See [lifecycle and cleanup](https://cognitio-agent.mintlify.site/cookbook/lifecycle.md) for complete script and service patterns.

## A conversation loses its memory

Each `agent.run()` starts a new session. Use one `await agent.createSession()` handle for messages that should share context. See [session memory](https://cognitio-agent.mintlify.site/cookbook/session-memory.md).

Resuming an ID requires the same backing runtime/database. The default isolated runtime's scratch data is removed when it closes successfully. Use [a persistent remote runtime](https://cognitio-agent.mintlify.site/cookbook/remote.md) for conversations that must outlive the local process.

## Streamed text appears twice

Completed assistant messages contain full text; partial events contain increments. Display one representation for the same response instead of appending both. See [streaming](https://cognitio-agent.mintlify.site/concepts/streaming.md) for the event types and examples.

## Collect useful diagnostics

Include the SDK version (`npm ls cognitio-agent-sdk`), Node/Bun version, operating system and architecture, model ID, terminal subtype or SDK error kind, and a small script that reproduces the problem. `session.getAppliedSettings()` helps confirm resolved session configuration; review and redact it before sharing.

Do not send API keys, auth headers, private files, or sensitive prompts. For a private report, use the [support contact](https://cognitio-agent.mintlify.site/support.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.