> For the complete documentation index, see [llms.txt](https://imbrace.gitbook.io/imbrace-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://imbrace.gitbook.io/imbrace-documentation/sdk/reference-and-guide/guides-and-advanced-workflows/troubleshooting.md).

# Troubleshooting

This section covers common iMBrace SDK and CLI issues listed in the Developer Manual.

#### AuthError: Invalid or expired API key

This usually means the API Key in `.env` has expired or is no longer valid.

Update the API Key:

```
IMBRACE_API_KEY=new_api_key
```

After updating the key, restart the application, test process, or CLI session so the new value is loaded.

#### ApiError 404 with double path in URL

This issue occurs when the `baseUrl` or `base_url` points to a full endpoint path instead of the Gateway root.

Incorrect:

```
IMBRACE_GATEWAY_URL=https://app-gatewayv2.imbrace.co/private/backend/v1/third_party_token
```

Correct:

```
IMBRACE_GATEWAY_URL=https://app-gatewayv2.imbrace.co
```

The SDK does not automatically read environment variables. `IMBRACE_GATEWAY_URL` is a convention for `.env`, but it still needs to be passed manually to the client constructor.

#### Integration tests are skipped

If all integration tests are skipped, `IMBRACE_API_KEY` is usually missing.

Set it temporarily during execution:

```
IMBRACE_API_KEY=api_xxx pytest tests/integration -v -m integration
```

Or add it to the Python `.env` file:

```
echo "IMBRACE_API_KEY=api_xxx" >> py/.env
```

#### TypeScript tests cannot find module

TypeScript test files need the correct relative import paths based on their folder depth.

Common import patterns:

| Test file location               | Import path                   |
| -------------------------------- | ----------------------------- |
| `tests/unit/*.test.ts`           | `../../src/client.js`         |
| `tests/unit/resources/*.test.ts` | `../../../src/resources/x.js` |
| `tests/integration/*.test.ts`    | `../../src/client.js`         |

#### mypy error: pattern matching is only supported in Python 3.10

This issue can occur if `mypy` scans `site-packages` by mistake.

Run:

```
mypy src/imbrace --exclude site-packages
```

#### CLI commands return 401 Unauthorized

A CLI `401 Unauthorized` response usually means the credential has expired or the API server has a stale token.

Log in again with an API Key:

```
imbrace login --api-key api_xxx...
```

#### CLI workflow run sync timeout

The `workflow run --sync` command may time out after around 60 seconds. For longer workflow executions, use asynchronous execution and then poll for the result.

Run the workflow asynchronously:

```
imbrace workflow run <flowId> --payload '{}'
```

Find the run ID:

```
imbrace workflow runs --limit 10
```

Check the result:

```
imbrace workflow run-detail <runId>
```

**Developer Reference:** [Troubleshooting](https://developer.imbrace.co/guides/troubleshooting/)