> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fivemesh.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK troubleshooting

> Resolve common FiveMesh SDK setup, permission and upload errors.

Use this page when the SDK resource starts but an export fails, returns an API error or cannot capture screenshots.

## Common errors

| Symptom                            | Check                                                                                                      |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `Missing FiveMesh API key`         | Confirm `set FIVEMESH_API_KEY "fm_live_..."` is in `server.cfg` before `ensure fivemesh-sdk`.              |
| `Missing FiveMesh API key profile` | Confirm the exact `FIVEMESH_API_KEY_<PROFILE_NAME>` ConVar exists for the `keyProfile` used by the export. |
| `FORBIDDEN`                        | Add the required CDN permission to the service key.                                                        |
| `PATH_NOT_ALLOWED`                 | Check the service key path prefix and the `path` passed to the export.                                     |
| Screenshot exports fail            | Confirm `screenshot-basic` is installed and started before `fivemesh-sdk`.                                 |
| Upload URL expired                 | Create a new upload URL and keep `expiresIn` short but long enough for the caller to upload.               |

## Check the service key

The SDK reads the service key from `FIVEMESH_API_KEY`.

```cfg theme={null}
set FIVEMESH_API_KEY "fm_live_..."
set FIVEMESH_API_KEY_MUGSHOTS "fm_live_..."
```

Create the key from **Account** > **API keys** and give it the exact CDN permission your export needs.

If an export uses `keyProfile = "MUGSHOTS"`, the SDK reads `FIVEMESH_API_KEY_MUGSHOTS`. Profile names are case-sensitive.

| Export                                                      | Required permission |
| ----------------------------------------------------------- | ------------------- |
| `listObjects`                                               | `cdn:read`          |
| `uploadFile`, `uploadImage`, `bulkUpload`                   | `cdn:write`         |
| `createPresignedUrl`, `takeServerImage`, client `takeImage` | `cdn:write`         |
| `deleteObject`, `bulkDelete`                                | `cdn:delete`        |
| `purgeObjects`                                              | `cdn:purge`         |

## Check the path scope

If the service key is scoped to `/screenshots`, keep uploads and deletes under that path.

```lua theme={null}
exports["fivemesh-sdk"]:uploadImage(dataUrl, nil, {
    path = "screenshots/profile",
    filename = "profile.webp"
})
```

Avoid absolute paths, backslashes and dot-prefixed segments.

## Check screenshot setup

Screenshot helpers require `screenshot-basic`.

```cfg theme={null}
ensure screenshot-basic
ensure fivemesh-sdk
```

If the call times out, increase the timeout passed to `takeServerImage` and confirm the target player is still connected.

## Related pages

* [Installation](/sdk/installation)
* [Server exports](/sdk/server-exports)
* [Screenshots](/sdk/screenshots)
* [API keys](/account/api-keys)