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

# Troubleshooting

> Collect safe evidence, isolate the failed KayanOS boundary, retry only when it is safe, and escalate with an actionable record.

## Troubleshoot the boundary, not the symptom alone

Most KayanOS problems happen at a boundary: the wrong organization, an unavailable published version, a role/scope mismatch, a missing field value, an offline synchronization step, a record lifecycle rule, a dashboard source query, a connection, or an API concurrency condition. A visible button, an empty list, or a generic error message is not enough to identify the cause.

Use this workflow for a Citizen Service Request before changing configuration or asking a user to repeat work. Start with a controlled non-production record whenever possible. Do not widen a role, publish a form, re-run an action, or recreate a request merely to see whether the symptom disappears.

![KayanOS troubleshooting view for a Citizen Service Request workflow.](https://kayanos.app/docs-images/en/reference/troubleshooting.png)

## Capture a safe incident record first

Collect enough evidence to reproduce and route the issue without copying secrets or private content:

| Collect                | Example                                                                                                                        | Do not collect/share                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| Exact outcome          | “Save returns a permission denial after changing `status`.”                                                                    | A paraphrase that loses the actual error text.                                   |
| Time and timezone      | `2026-07-12 14:20 Asia/Damascus` or the organization’s configured timezone.                                                    | Assumed local time with no timezone.                                             |
| Organization and actor | Organization name/ID, member role, public participant type, or integration token **name/hint**.                                | Password, full API token, sign-in code, private key, or enrollment secret.       |
| Target                 | Sanitized record/reference, form/session reference, entity key, dashboard/widget, template, export job, or automation run ID.  | Full citizen record, attachment contents, or a signed file URL.                  |
| Action/context         | URL or module, form version, selected status, scope/Service Centre, browser/app version, and steps immediately before failure. | Screenshots showing personal data or hidden credentials.                         |
| Error evidence         | Exact visible message, API `x-request-id`, run/job ID, or safe screenshot.                                                     | Browser console dumps containing Authorization headers or confidential payloads. |

Give the incident a short title that states the boundary: “Inspector cannot submit offline inspection after reconnecting” is actionable; “KayanOS broken” is not.

## Follow the same diagnostic order

1. **Reproduce safely.** Can the intended role reproduce the symptom with an approved non-production request? Record exact steps and the expected result.
2. **Check the organization and identity.** Confirm the selected organization, signed-in member/public participant, role, scope, form session owner, or integration token owner.
3. **Check availability.** Confirm the feature is released, the form/version/template/dashboard/connection is configured for this use, and required publication/expiry/limit conditions are satisfied.
4. **Check data and state.** Review required values, field types, options, relations, record status, form session status, version, and current lifecycle rule.
5. **Check the auditable boundary.** Inspect the safe run/job/request/session/reference evidence. For an API problem, retain `x-request-id`; for a KayanOS Automation, retain run ID; for an offline session, retain local submission ID and server session ID if available.
6. **Choose the smallest safe remedy.** Correct one known wrong setting/value, then re-test the same case. Do not batch unrelated changes.
7. **Document the outcome.** Record root cause, change, test result, remaining risk, and owner. If the cause is not established, escalate rather than guessing.

## Symptom index

| Symptom                                  | First boundary to check                                                         | Safe next step                                                                                     |
| ---------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| A menu, entity, or action is missing     | Organization, released surface, role/verb, scope                                | Compare the intended role with a denied role; do not grant owner access as a test.                 |
| Record is visible but will not open/save | Open/update verb, record scope, field rule, status/lifecycle                    | Capture the target record scope/status and exact field/action.                                     |
| Form cannot start or session cannot open | Form type/version, initiate/open permission, public/session owner boundary      | Confirm regular/public/offline path and the session’s initiator/version.                           |
| Offline work does not arrive             | Queue state, connectivity, auth, local file, sync start/commit                  | Preserve local session/files; inspect `pending`/`failed` evidence before creating another session. |
| Public form does not appear/start        | Public enablement, regular/published version, end date, cap, account condition  | Check all eligibility conditions and a clean public-browser session.                               |
| Dashboard is blank/denied                | Widget source/filter/configuration and viewer source permissions                | Validate against a known record and viewer scope; distinguish zero from denial.                    |
| Template render/filename is wrong        | Record context, tag/expression, lookup mode/allow-list, output/template version | Use a controlled record and inspect the rendered result, not just the DOCX source.                 |
| Serial/calculated value is unexpected    | Field configuration, source data, expression, timing/dependency                 | Compare settings and inputs with a known expected result.                                          |
| API returns an error                     | Token state/owner, entity/field eligibility, body/filter, rate limit, `ETag`    | Retain status, envelope code, `x-request-id`, and rate/ETag headers; never log the secret.         |
| Export fails or download disappears      | Job state, selected data/permissions, retention/expiry                          | Record job ID/status and re-run only after reviewing the failure.                                  |
| Automation run does not fire or fails    | KayanOS connection, trigger/filter, target release/state, runtime role/scope    | Retain run ID and test data; do not repeatedly run a side-effecting flow.                          |

## Permission and availability failures

When something is missing, disabled, or refused, distinguish **visibility** from **authorization**. A navigation item can appear even though an operation on a specific record is denied. A selector can be visible while all eligible results are outside the member’s scope. A form expression can show a button while the server refuses the action.

Check in this order:

1. Correct organization and active identity.
2. Resource and exact verb required for the operation.
3. Target record/session scope and hierarchy relation.
4. Field-level read/update rule, if a particular field is involved.
5. Current status, action, signature, or lifecycle rule.
6. Publication/connection/feature condition for the selected surface.

Run both an allowed and a deliberately denied test. If both succeed, the access boundary is too broad. If both fail, the issue may be configuration/state rather than the individual role.

See [Permissions and availability](/reference/permissions-and-availability) for the full decision chain.

## Form and session failures

| Symptom                            | Evidence to collect                                                   | Safe remedy                                                                                                   |
| ---------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Cannot initiate                    | Form ID/version/type, actor role, organization, exact denial          | Confirm `initiate` permission and published/expected version; use the correct public or offline path.         |
| Session is read-only               | Session type/status, starter/participant, item state                  | For submitted offline work, preserve it and verify sync/review; do not alter it through an unrelated account. |
| Required field blocks submit       | Field key, condition, current/parent/repeater values, validation text | Reproduce with one controlled row and check local context/required expression.                                |
| Repeatable row behaves differently | Row index, parent/sibling values, repeatable type, first/later row    | Test each instance and avoid treating `$index` as a durable identifier.                                       |
| File unavailable                   | Session reference, field path, sync state, authorized actor           | Verify upload/sync completion and session access; do not circulate signed links.                              |
| Public participant denied          | Public session owner/account state, form eligibility                  | Confirm participant/session match and public settings, not staff permissions.                                 |

For an action/signature issue, record action key, status before/after, actor, and response—not the full sensitive action payload.

## Offline synchronization failures

Offline sessions have `pending`, `syncing`, `failed`, and `synced` states. A submitted local session is not centrally received until it is `synced`. Keep the device and its local files intact while diagnosing.

1. Record the local submission ID, form/version, device-created/submitted times, queue state, attempts, next retry time, and last safe error.
2. Confirm the device is online and the starter has a usable authenticated session. Do not enter another person’s credentials to “unstick” it.
3. Check local storage and each attached file. A file upload failure must not be solved by deleting the file.
4. Let the approved retry path run after connectivity/authentication is restored. The client uses bounded backoff; repeated manual resubmission can create confusion.
5. When `synced`, open the server session and compare fields, repeatables, files, and timestamps. If the server session is incomplete, escalate with both local and server references.

Use [Offline forms](/build/offline-forms) for the full state/recovery model.

## Data model, serial, calculated field, and template failures

### Entity fields and layouts

Check the field key, type, required/default rule, select option value, relation target, layout visibility, and field-specific permission. A display label is not the stored key, and a hidden field may still have a saved value or be unavailable for a reason unrelated to layout.

### Serial IDs

Capture serial field configuration, namespace/format expression, sequence/start value, date/timezone inputs, generation mode, current record state, and the expected reference. Do not manually edit a serial to hide a collision or gap. Test with a controlled record and compare preview/configuration with the stored outcome. See [Serial IDs](/build/serial-ids).

### Calculated fields

Capture the formula, value type, direct/inverse relation setup, source values, result, status, and recalculation timing. Check null/empty arrays and missing relations before treating a zero/blank result as a logic failure. For a dependency/cycle error, stop editing related calculations in bulk and isolate the smallest cycle. See [Calculated fields](/build/calculated-fields).

### Document templates

Capture template/version, target record, output format, filename expression, caller/admin execution mode, non-empty administrative allow-list if used, tag/expression, and rendered output. Test missing optional values, empty relations, allowed/denied lookup targets, and file name separately. Do not paste a real document or credential into a support request. See [Document templates](/build/document-templates) and [Document-template tags and rendering](/build/document-template-tags-and-rendering).

## Dashboard, API, export, and automation failures

### Dashboards

Compare a widget with one known source record. Capture widget type, entity/source, fixed and viewer filters, aggregation/date basis, viewer role/scope, and whether the UI reports no data or permission denial. Do not replace a denied entity query with a copied sensitive manual number; correct the source access/configuration.

### Public API

Record HTTP status, error code/message, `x-request-id`, token **name/hint**, endpoint, entity key, field key, sanitized request body, rate-limit headers, and `ETag`/`If-Match` where relevant. Common corrections are: rotate/re-authorize a token, enable an entity, fix a public-queryable field/filter, honor `retry-after`, or re-read after `412 PRECONDITION_FAILED`. Never retry a create/delete blindly after a timeout.

### Export jobs

Record job ID, owner, selected entities, value representation, date basis, requested system columns, status, expiry/retention state, and error. Exports are access-controlled but can still be sensitive; do not move a file to an unapproved location while troubleshooting.

### KayanOS Automations

Record flow/run ID, KayanOS connection selected, trigger/action, exact filter values, test record/session reference, target availability, and safe error output. A test can create or modify KayanOS-side data. Use an approved non-production request, verify source and target, and avoid repeated runs until you know whether the first run had a side effect.

## Safe retry versus escalation

| You may retry after checking                                                                      | Escalate before retrying                                                                                            |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| A read-only dashboard refresh after confirming source availability.                               | A create, delete, external/side-effecting automation action, or status transition whose first outcome is unknown.   |
| An API read after respecting `retry-after`.                                                       | A duplicate-label/conflict/ETag failure without reconciling the current record.                                     |
| Offline sync after restoring connectivity/authentication while preserving the same local session. | A failed sync involving uncertain file loss, an existing incomplete server session, or a different starter account. |
| A template render against a controlled non-production record.                                     | A production document render/send that could expose a wrong recipient or sensitive lookup.                          |
| A viewer filter change within approved access scope.                                              | A permission, role, or scope expansion affecting multiple people.                                                   |

## Escalation packet

When the issue needs an administrator or support owner, send a concise sanitized packet:

```txt theme={null}
Title: <boundary and symptom>
Organization: <name or ID>
Time/timezone: <ISO time and timezone>
Actor: <member role / public participant type / token name-hint>
Target: <sanitized record, session, job, run, or request ID>
Expected: <what should happen>
Actual: <what happened, exact safe error>
Steps: <minimal reproduction>
Evidence: <safe screenshot, x-request-id/run ID, relevant status>
Changes already tried: <one or none>
Risk/side effect: <none / possible duplicate / access exposure / other>
```

Do not include secrets, raw credentials, full citizen data, signed file URLs, or unredacted exports. If data exposure is suspected, stop further sharing/retries and follow the organization’s incident process immediately.

## Related guides

* [Permissions and availability](/reference/permissions-and-availability)
* [Form submissions](/build/form-submissions)
* [Offline forms](/build/offline-forms)
* [Public portal](/build/public-portal)
* [Public API reference](/reference/public-api)
* [Serial IDs](/build/serial-ids)
* [Calculated fields](/build/calculated-fields)
* [Document templates](/build/document-templates)
* [KayanOS Automations test, run, and troubleshoot](/build/automations-test-run-and-troubleshoot)