---
title: Common Errors
description: Static SDK-level error catalog -- CLI errors, deployment errors, schema validation, platform tool failures, and runtime errors with diagnostic steps
---

This is the static SDK-level error catalog. Check `.claude/memory/errors/` first for workspace-specific fixes. Use this file when the error is new to the workspace or when the memory has no match.

---

## CLI Errors

### ELEVASIS_PLATFORM_KEY not set

**Cause:** The `.env` file is missing the API key, or the file was not loaded.

**Fix:**

1. Check that `.env` exists in the project root (or any parent directory)
2. Confirm it contains `ELEVASIS_PLATFORM_KEY=sk_...`
3. The CLI walks up directories to find `.env`, so running from subdirectories like `operations/` works automatically
4. If the file exists with the right content, run `elevasis-sdk check` again

### Cannot connect to API

**Cause:** Network issue or the API URL is incorrect.

**Fix:**

1. Check your internet connection
2. If using a custom API URL via `--api-url` or `ELEVASIS_API_URL`, verify it is correct
3. Remove `NODE_ENV=development` from `.env` if you are not running a local API server

### NODE_ENV=development in .env

**Cause:** The SDK is pointing at a local API server (port 5170 by default) instead of the hosted platform.

**Fix:** Remove `NODE_ENV=development` from `.env`. The CLI connects to the hosted platform by default.

---

## Validation Errors (elevasis-sdk check)

### Duplicate resource ID

**Message:** `Duplicate resource ID 'name' in organization 'org'`

**Cause:** Two resources in `src/` share the same `resourceId`.

**Fix:** Each resource must have a unique `resourceId` within your organization. Check all domain directories in `src/` and rename the duplicate.

### Workflow step references non-existent next step

**Message:** `Workflow step 'stepA' references non-existent next step 'stepB'`

**Cause:** A step's `next.target` or `next.routes[*].target` points to a step name that does not exist in the `steps` record.

**Fix:** Check the spelling of the target step name. All target values must exactly match keys in the `steps` object.

### Missing entryPoint

**Cause:** The workflow's `entryPoint` field names a step that does not exist in `steps`.

**Fix:** Confirm `entryPoint` matches an exact key in your `steps` record.

---

## Schema Validation Errors

### Schema validation failed (input)

**Message:** `Schema validation failed` with field-level details

**Cause:** The input passed to the workflow does not match the `inputSchema`.

**Fix:**

1. Read the error's field details -- it names the failing field and expected type
2. Compare against your `inputSchema` definition
3. Common causes: wrong type (string vs number), missing required field, extra field not in schema, misspelled field name
4. Check that `z.infer` types match what your handler actually receives

### outputSchema validation failed

**Cause:** Your handler's return value does not match the workflow's `outputSchema`.

**Fix:**

1. Compare what your handler returns to what `outputSchema` expects
2. Check field names for typos (the schema says `companyName`, handler returns `company_name`)
3. Check types -- the schema says `z.number()` but the handler returns a string
4. Check required vs optional -- do not return undefined for a required field

### Cannot find name 'z'

**Cause:** Missing Zod import.

**Fix:** Add `import { z } from 'zod'` at the top of the file.

---

## TypeScript Errors

### Type 'X' is not assignable to type 'Y'

**Cause:** The data flowing into a step or returned from a handler does not match the declared type.

**Fix:**

1. Check the input type annotation on the handler: `async (input: MyInput) => ...`
2. Confirm the `z.infer<typeof mySchema>` type matches what the previous step returns
3. Check that all optional fields are handled (do not assume they are always present)

### Cannot find module '@elevasis/sdk'

**Cause:** Dependencies are not installed.

**Fix:** Run `pnpm install` in the workspace root.

### Cannot find module '@elevasis/sdk/worker'

**Cause:** Dependencies not installed, or using an old SDK version that does not export the `worker` subpath.

**Fix:**

1. Run `pnpm install`
2. Check that `@elevasis/sdk` version is recent enough to include `worker` export
3. Confirm your `tsconfig.json` has `"moduleResolution": "Bundler"` or `"NodeNext"`

---

## Platform Tool Errors

### PlatformToolError: credential not found

**Cause:** The credential name passed to `platform.call()` does not match any credential stored in the platform.

**Fix:**

1. Check spelling and case -- credential names are case-sensitive
2. Open the command center and confirm the credential exists and is named exactly as referenced
3. Check that the credential belongs to the correct organization

### PlatformToolError: credentials_invalid

**Cause:** The credential exists but has the wrong shape for the tool being called.

**Fix:**

1. For the `http` tool: verify the credential type matches the API's auth method (bearer, api-key-header, basic, etc.)
2. For the Supabase tool: verify the credential contains `url` and `serviceRoleKey` fields
3. Re-create the credential in the command center if the format is wrong

### PlatformToolError: timeout_error

**Cause:** The platform tool call took longer than 30 minutes (the `platform.call()` safety-net timeout; real per-tool enforcement is server-side).

**Fix:**

1. Check if the external API is slow or down
2. Reduce the amount of data being processed in a single call
3. For `http` tool: the external endpoint may be unresponsive -- check directly

### PlatformToolError: service_unavailable

**Cause:** The platform service or integration adapter is not available.

**Fix:**

1. Check the Elevasis status page
2. Retry -- transient availability issues resolve quickly

---

## Runtime Errors

### Execution timeout

**Cause:** The entire execution exceeded the platform ceiling (2 hours by default; agents can override via `constraints.timeout`).

**Fix:**

1. Identify which step is slow -- check execution logs for step timing
2. Reduce work per step or parallelize if possible
3. For long-running operations, consider breaking into multiple workflows with the `execution` platform tool to chain them

### Worker ran out of memory (256MB limit)

**Cause:** The workflow processed too much data in memory at once.

**Fix:**

1. Reduce the size of data loaded per execution
2. Use pagination for large data sets (fetch in chunks, process one at a time)
3. Avoid loading large files or arrays entirely into memory

### Module resolution error at runtime

**Cause:** An import in your workflow bundle cannot be resolved.

**Fix:**

1. Run `elevasis-sdk check` -- it catches most resolution errors before deploy
2. If the import is a built-in Node.js module, ensure it is compatible with the worker environment
3. Avoid imports that require file system access or native modules

---

## Memory Error Structure

When recording a new error in `.claude/memory/errors/`, use this table format:

```
| Error | Context | Fix | Count | Last Seen | Status |
| --- | --- | --- | --- | --- | --- |
| `Schema validation failed` on lead-scorer | Added score field | Changed score from z.string() to z.number() | 1 | 2026-02-26 | Resolved |
```

Status values: `Resolved` (fixed this session), `Recurring` (seen 2+ times), `Promoted` (3+ times, now in Rules).

---

**Last Updated:** 2026-02-26
