@elevasis/sdk 1.25.0 → 1.26.1

package/reference/troubleshooting.mdx

@@ -1,223 +1,222 @@
----
-title: Common Errors
-description: Static SDK-level error catalog -- CLI errors, deployment errors, schema validation, platform tool failures, and runtime errors with diagnostic steps
-loadWhen: "Debugging an unknown error not found in workspace memory"
----
-
-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 60 seconds.
-
-**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 (300s)
-
-**Cause:** The entire workflow execution exceeded the 300-second limit.
-
-**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
+---
+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 60 seconds.
+
+**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 (300s)
+
+**Cause:** The entire workflow execution exceeded the 300-second limit.
+
+**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