Error Codes

Last updated April 7, 2026

Platform error codes, their meanings, and recovery actions.

KB Labs uses structured error codes throughout — in CLI output, REST API responses, and workflow logs. This page catalogs the known codes by subsystem.

Error shape

CLI output (JSON mode):

JSON

{
  "ok": false,
  "error": {
    "code": "CONFIG_NOT_RESOLVED",
    "message": "No profile matched the current environment",
    "details": { "profileId": "production" }
  },
  "result": null,
  "meta": {}
}

Commands return one canonical envelope: { ok: true, result?, meta? } on success or { ok: false, error, result?, meta? } on failure. The result field carries plugin business data; meta carries optional execution metadata. A command's process exit code is an execution detail and is not part of the plugin result contract.

REST API:

JSON

{
  "error": {
    "code": "WORKFLOW_NOT_FOUND",
    "message": "Workflow run abc123 not found",
    "details": {}
  }
}

Thrown exceptions (caught by the runtime and mapped to one of the above):

TypeScript

throw new PluginError('INVALID_HANDLER', 'Handler at ./dist/run.js does not export execute');

Defining errors in plugins

Use defineError from @kb-labs/sdk to declare typed error codes in your plugin:

TypeScript

import { defineError } from '@kb-labs/sdk';
 
export const MyPluginErrors = {
  CONFIG_MISSING: defineError('CONFIG_MISSING', 400, 'Plugin configuration is missing'),
  LLM_UNAVAILABLE: defineError('LLM_UNAVAILABLE', 503, 'LLM adapter not configured'),
  PARSE_FAILED: defineError('PARSE_FAILED', 422, 'Failed to parse LLM response'),
};

commonErrors from @kb-labs/sdk provides pre-defined codes for the most frequent cases.

Platform error codes

Plugin loading

Code	HTTP	Meaning	Fix
`INVALID_MANIFEST`	400	Manifest failed schema validation	Check `schema`, `id`, `version` fields are correct
`INVALID_HANDLER`	400	Handler file not found or missing `execute` export	Verify the `handler` path in the manifest points to built `.js` output
`PLUGIN_NOT_FOUND`	404	Plugin ID not in registry	Install the plugin or clear registry cache
`PLUGIN_CONFLICT`	409	Two plugins declare the same command ID	Rename one command's `id`
`CIRCULAR_DEPENDENCY`	400	Plugin dependency graph has a cycle	Check `dependencies[]` in manifests
`MISSING_DEPENDENCY`	400	Required plugin not installed	Install the dependency listed in `plugin.dependencies`

Configuration

Code	HTTP	Meaning	Fix
`CONFIG_NOT_FOUND`	404	`.kb/kb.config.json` missing	Run `pnpm kb init` or restore from backup
`CONFIG_NOT_RESOLVED`	400	No profile matched current environment	Check `profiles` in `kb.config.json`
`CONFIG_PARSE_ERROR`	400	`kb.config.json` is invalid JSON	Fix JSON syntax
`ADAPTER_NOT_CONFIGURED`	400	Required adapter missing from config	Add adapter to `kb.config.json`

Execution

Code	HTTP	Meaning	Fix
`EXECUTION_TIMEOUT`	504	Handler exceeded `timeoutMs`	Increase timeout in manifest or optimize handler
`EXECUTION_ERROR`	500	Handler threw an unhandled exception	Check logs: `kb-dev logs rest`
`HOST_MISMATCH`	400	Handler invoked from wrong host type	Use `defineRoute` for REST handlers, `defineCommand` for CLI
`SANDBOX_ERROR`	500	Plugin sandbox failed to initialize	Run `pnpm kb marketplace plugins doctor`

Workflow

Code	HTTP	Meaning	Fix
`WORKFLOW_NOT_FOUND`	404	Workflow ID not registered	Check workflow handler declarations in manifests
`WORKFLOW_RUN_NOT_FOUND`	404	Run ID doesn't exist	Verify run ID
`WORKFLOW_ALREADY_CANCELLED`	409	Run was already cancelled	—
`JOB_NOT_FOUND`	404	Job handler ID not registered	Check `jobs.handlers[]` in manifest
`STEP_FAILED`	500	A workflow step threw	Check run logs for step error

Rate limiting and quotas

Code	HTTP	Meaning	Fix
`RATE_LIMIT_EXCEEDED`	429	Too many requests for tenant	Check `Retry-After` header; reduce request rate
`QUOTA_EXCEEDED`	429	Tenant exceeded daily/monthly quota	Upgrade tier or wait for quota reset
`CONCURRENT_LIMIT_EXCEEDED`	429	Too many concurrent workflow runs	Wait for running workflows to finish

Authentication and authorization

Code	HTTP	Meaning	Fix
`UNAUTHORIZED`	401	Missing or invalid auth token	Provide `Authorization: Bearer <token>` header
`FORBIDDEN`	403	Token valid but insufficient permissions	Check plugin permissions and tenant tier
`PERMISSION_DENIED`	403	Plugin permission check failed	Check `permissions` in manifest; request needed grants

Command results, diagnostics, and retries

The command result envelope separates plugin business outcome from worker execution. A command may write useful diagnostics to stderr; those diagnostics are retained and streamed, but stderr alone does not make a command unsuccessful. A command is unsuccessful when it returns ok: false or the execution layer cannot complete it.

Workflow retries are policy-driven. A step is not retried merely because it produced stderr: retry requires an explicit failure and a retry policy that permits the failure classification. Network, timeout, rate-limit, and server failures are classified as transient when appropriate, while non-idempotent operations may still require an idempotency key before they can be retried.

Plugin and adapter authors should use the shared classifier from the SDK facade instead of defining local error-code or message-matching rules:

TypeScript

import { classifyFailure } from '@kb-labs/sdk';
 
const failure = classifyFailure(error, {
  source: 'command',
  phase: 'running',
});

The same taxonomy is used by CLI, execution, adapters, and workflow hosts.

Diagnosing errors

Get more context:

Bash

LOG_LEVEL=debug pnpm kb <command>     # verbose output
kb-dev logs rest                       # last 50 lines from REST API
kb-dev logs rest -f                    # follow in real time

Plugin loading issues:

Bash

pnpm kb marketplace plugins doctor     # diagnose all installed plugins
pnpm kb marketplace plugins refresh # clear all caches and retry

Workflow failures:

Bash

pnpm kb workflow:logs --run-id <id>    # full run log
# Or via REST:
GET http://localhost:5050/api/v1/workflows/runs/<id>
GET http://localhost:5050/api/v1/workflows/runs/<id>/logs

Common error patterns and fixes

"Plugin not found: @kb-labs/qa" / showing only test plugins

Zombie host-agent daemon processes are intercepting plugin execution:

Bash

pkill -9 -f "host-agent-app/dist/index.js"
pnpm kb marketplace plugins refresh

"Command not found" after building a plugin

Registry cache is stale:

Bash

pnpm kb marketplace plugins refresh

"Cannot find module '@kb-labs/...'"

Dependencies not built in the right order:

Bash

npx kb-devkit-build-order --package=your-package