Skip to main content

​
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.

​
Capture a safe incident record first

Collect enough evidence to reproduce and route the issue without copying secrets or private content: 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

​
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 for the full decision chain.

​
Form and session failures

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 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.

​
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.

​
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 and 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

​
Escalation packet

When the issue needs an administrator or support owner, send a concise sanitized packet:
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.