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

> ## Agent Instructions
> Video walkthroughs: the Dimension product overview video (https://www.youtube.com/watch?v=Mx8rg5wfkU0, also embedded at https://docs.dimension.io/overview) is the first of a series. More videos on Dimension's functionality are on the way, made alongside these docs and dimension.io. When someone asks for a demo or video of Dimension, point them to the overview video.

# Troubleshooting

> Common errors and recovery paths across Data Feeds, Actions, and Studio

A consolidated guide to common problems and how to recover. Organised by pillar, then by symptom. For a list of error codes and messages and where they appear, see [Error Codes](https://docs.dimension.io/reference/error-codes.md).

## Data Feeds

### Symptom — Test returns 401 / 403

**Cause:** auth credentials wrong or expired.

**Fix:**

1. Open the Data Feed editor
2. **Variables panel** — re-enter the auth value
3. Click the lock icon to encrypt
4. Click **Test** again

For OAuth2 tokens with short TTLs, ask Composer to add token-refresh logic:

```text theme={null}
"Add OAuth2 client-credentials token refresh. Cache the token
for its TTL and re-fetch when it expires."
```

### Symptom — Test returns 404

**Cause:** wrong endpoint URL, or the resource doesn't exist for your auth scope.

**Fix:**

* Double-check the URL — including path version (`/v1` vs `/v2`)
* Verify your auth has read access to the resource in the source platform
* For tenant-scoped APIs, confirm the tenant ID in the URL

### Symptom — Test returns 200 but "0 records ingested"

**Cause:** Data Path is pointing at the wrong place in the response.

**Fix:**

1. Click **Test** — view the actual response in the right-hand panel
2. Find the array of records in the response body
3. Open **⋯ → Advanced → Schema** to see what Composer inferred
4. Adjust the **Data Path** to point at the records array

See [JSON Path Reference](https://docs.dimension.io/reference/json-paths.md) for examples.

### Symptom — Pagination only pulls the first page

**Cause:** pagination config doesn't match the API's actual paging pattern.

**Fix:**

* Inspect a successful response to see if pagination is via Link header, body cursor, page number, or offset
* Update the Pagination section to the matching pattern
* For cursor pagination, double-check the JSONPath to the cursor and the request param name

### Symptom — Sync fails with "Timeout"

**Cause:** the source API took too long to respond.

**Fix:**

* Add **Pagination** if you haven't (small pages return faster than one big request)
* Reduce page size if you have it (try `size=100` instead of `size=1000`)
* For very large datasets, use **Limit/Offset** so each page is bounded

### Symptom — "Please publish this data feed in order to trigger a run"

**Cause:** the feed is in Draft. Scheduled syncs only run on Published feeds.

**Fix:** click **Published** at the bottom of the editor.

### Symptom — Studio app shows stale data after Feed update

**Cause:** the Feed has been updated and re-tested, but the last successful sync run is old.

**Fix:**

* Open the Feed → click the refresh icon at the top right of the canvas (this re-runs against Published)
* Or wait for the next scheduled sync
* Or in Studio, ask Composer: *"Force a refresh of the X data feed"* — Composer adds a manual-refresh button to the app

### Symptom — Sync intermittently fails

**Cause:** transient source API issues; or rate limiting from the source.

**Fix:**

* Open **⋯ → Advanced → Request History** — look at the timing of failures
* If they cluster around specific times, the source may have a maintenance window — adjust the schedule
* If they're rate-limit responses (429), reduce sync cadence or add per-request delay via Composer

## Actions

### Symptom — Action invocation does nothing

**Cause:** Action isn't published, or the wiring in the Studio app isn't actually firing.

**Fix:**

1. Open the Action editor → ensure it's **Published**
2. In the Studio app, click **Inspect Component** → click the button you expect to fire the Action
3. In Composer: *"What Action does this button invoke?"* — Composer will tell you, or report no wiring

### Symptom — Webhook returns non-2xx response

**Cause:** the destination rejected the payload, auth, or URL.

**Fix:**

* Open **Settings → Logs → Request History** to see the response code and body
* Most common causes: wrong URL, expired auth, malformed JSON in the body
* Use the Action editor's **Test** panel with sample inputs to reproduce

### Symptom — Email Action sends nothing

**Cause:** recipient must be a tenant user. Free-form addresses are rejected.

**Fix:**

* In the Action editor, click into Recipients — only tenant users appear in the autocomplete
* To email external addresses, replace the Email Action with a **Webhook Action** targeting your email API (SendGrid, Postmark, AWS SES)

### Symptom — Webhook works in Test but not from the live app

**Cause:** input mapping in the Studio app doesn't match the Action's declared inputs.

**Fix:**

* Open the Action editor and note the input names + types
* In the Studio app, use Inspect Component on the firing button: *"Make sure the inputs to the X Action are mapped from the current row's fields"*

### Symptom — Auth token in a Webhook header expired

**Cause:** secret rotation upstream; the Action still has the old value.

**Fix:**

* Open the Action editor → **Variables** panel
* Re-enter the new secret → click the lock icon to encrypt
* Test, then save

## Studio

### Symptom — Composer says "I can't find a field called X"

**Cause:** the field doesn't exist in the schema, or has been renamed.

**Fix:**

* Open the Data Feed → **⋯ → Advanced → Schema** to see actual fields
* Ask Composer: *"Show me what fields are available on the X data feed"*
* Reference the real field name in the next prompt

### Symptom — Preview is blank after a prompt

**Cause:** generated code has a runtime error.

**Fix:**

1. Open **X-Ray → Files** → look at `App.tsx` and any recently-modified file
2. Most errors have an inline indicator
3. Ask Composer: *"Fix the error in App.tsx — it's currently throwing on render"*
4. Or **Restore checkpoint** to the previous working state and re-prompt with a smaller change

### Symptom — Composer rewrote a working component when I asked for a small change

**Cause:** the prompt was too high-level; Composer interpreted it as a broader change.

**Fix:**

* **Restore checkpoint** to before the prompt
* Use **Inspect Component** on the specific element
* Re-prompt with a focused instruction — *"This card — change the title font size to 24px, nothing else"*

### Symptom — Hit the AI Credit limit mid-build

**Cause:** lots of generation in the billing period.

**Fix:**

* Check **Settings → Usage** for the billing period reset date
* Wait for the reset, or contact sales to raise the limit
* Use **Restore checkpoint** + iterative prompts instead of full rebuilds — much cheaper per change

### Symptom — Inspect Component selects the wrong element

**Cause:** the element you wanted is inside another component that grabs the click first.

**Fix:**

* Click slightly off-centre, away from interactive children
* Or describe the element in the prompt: *"The donut chart in the top-right corner — make it 50% taller"*
* Or open the element's parent first and then drill down

### Symptom — Publish button is disabled

**Cause:** there's nothing to publish — the Draft matches the Published version, or the Composer is still generating.

**Fix:**

* Make at least one change to the Draft
* Wait for any in-progress Composer prompt to finish

### Symptom — Share URL menu item is greyed out

**Cause:** the app is in Draft and not yet Published.

**Fix:** click **Publish**. Share URL becomes available immediately after.

### Symptom — App works for me but not for a teammate

**Causes & fixes:**

| Cause | Fix |
| - | - |
| App is in Draft | Publish it |
| Teammate doesn't have workspace access | Share the workspace or move app to one they can see |
| Teammate's role is too low | Settings → Users → assign a role with read access |
| App uses a Data Feed that's also in Draft | Publish the Data Feed |
| Teammate isn't in the app's workspace | Add them, their Team or everyone to the workspace's **Access** list |

### Symptom — Generate PDF returns an error

**Causes & fixes:**

| Cause | Fix |
| - | - |
| App takes >60s to render fully | Filter the view to reduce data before exporting |
| Custom fonts not loaded | Use system / web-safe fonts in the brand styling |
| Data Feed errored mid-render | Refresh the Feed, then re-export |

## Platform-wide

### Symptom — Command Menu (⌘K) doesn't open

**Cause:** focus is in an input that captures the keystroke.

**Fix:** click anywhere on the page background first, then press ⌘K. Or click the **Search...** field in the header and you'll see the Command Menu button.

### Symptom — Onboarding tour reappeared

**Cause:** new device, new session, or onboarding state was reset.

**Fix:** click **Skip** to dismiss permanently. Re-run any app's tutorial via **⋯ → Show Tutorial** in the editor.

### Symptom — Notifications bell shows red dot but the panel is empty

**Cause:** notifications cleared during the same session that fired them.

**Fix:** click **Clear** in the panel to reset the red-dot indicator.

### Symptom — Workspace switcher empty / "0 workspaces"

**Cause:** you don't have access to any workspaces in this tenant.

**Fix:**

* Ask a Super Admin to grant you access to a workspace
* Or create your own — click **+ New** in the workspace switcher

### Symptom — "Sorry, a resource cannot be found" (404)

**Cause:** stale URL — the artefact has been deleted or migrated.

**Fix:** navigate back to the Workspace overview from the breadcrumb and find the artefact in the relevant list.

### Symptom — Audit Log doesn't show my recent action

**Cause:** small lag in indexing.

**Fix:** wait 30 seconds and refresh. If still missing after a minute, contact support.

## FAQ

Questions that aren't about a specific error are on the [FAQs](https://docs.dimension.io/reference/faqs.md) page.

## Where to file bugs

| Type | Channel |
| - | - |
| **General bug** | Chat Widget (bottom-right of every page) → `Report a bug` |
| **Suspected security issue** | `security@threataware.com` |
| **Feature request** | `support@threataware.com` |
| **Roadmap question** | Your account manager, or `sales@threataware.com` |
| **Documentation issue** | Click "Edit this page" at the bottom of any docs page (if available) or `docs@threataware.com` |

## See also

> [card] [JSON Path Reference](https://docs.dimension.io/reference/json-paths.md)
>
> Worked examples for Data / ID / Capture Variables paths

> [card] [Composer Prompt Engineering](https://docs.dimension.io/reference/prompt-engineering.md)
>
> Patterns that produce reliable Composer output

> [card] [Migration Playbook](https://docs.dimension.io/reference/migration-playbook.md)
>
> Move apps between workspaces and tenants

> [card] [Error Codes](https://docs.dimension.io/reference/error-codes.md)
>
> Every error code and message, and where it appears


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.