---
title: "Troubleshooting"
description: "Symptoms, likely causes, confirmation steps, and fixes for common ZeyOS app problems."
canonical_url: "https://www.zeyos.com/ixml/ixml-guide/development-environment/troubleshooting"
markdown_url: "https://www.zeyos.com/ai/guide/ixml/ixml-guide/development-environment/troubleshooting.md"
section: "ixml-guide"
authority: "guide"
language: "en"
source_repository: "zeyos/guide"
source_path: "docs/ixml/03-development-environment/troubleshooting.md"
source_revision: "cce886a8da98cd124ee3644711085bbdcf1a87ce"
---
# Troubleshooting
Start from the symptom. Before changing code, identify the [execution context](https://www.zeyos.com/ixml/ixml-guide/development-environment/execution-contexts), because the same symptom has different causes in different contexts. Evidence labels have the same meaning as on that page.
## Blank weblet
**Likely causes**
- The frame request failed with 401 or 403, or the app is inactive.
- The weblet is on a `.form` view, where plain output is discarded.
- The asset has no deployed code, so the platform returns an empty response.
- Output text was discarded by [result propagation](#text-disappears-from-output).
- A script error occurred after the frame loaded.
**How to confirm**
1. Open browser developer tools and find the request for the frame.
2. Read its status and response body. Status 200 with an empty body means the script produced nothing.
3. Check the `view` ending and the `type` in the manifest.
4. Run `zeysdk compare` to confirm that the deployed code matches yours.
**Fix**
Correct the status cause, deploy the code, or move the weblet to a view that matches how it renders. Use form commands in `.form` views and `output` elsewhere. `zeysdk run` cannot reproduce this problem, because it has no session and no frame.
## A protected route accepts a request with no token
**Likely causes**
- The handler reads `AUTH` without ``, so a query argument or form field supplies it.
- The check sits before `rest:server`, and the handler still reads a forgeable `$AUTH.*`.
- The handler has no check. The platform does not reject anonymous calls for you, even for a restricted application.
**How to confirm**
Send `?AUTH[user]=1` with no token, using `curl -g`. A 200 confirms the problem.
**Fix**
Add `use` as the first child of every `rest:resource`, for every global the handler reads. See [Bind globals inside `rest:resource`](https://www.zeyos.com/ixml/ixml-guide/development-environment/execution-contexts#bind-globals-inside-restresource). Treat any past use of such a route as unauthenticated.
## Unauthenticated or forbidden service call from a weblet
**Likely causes**
- The weblet's JavaScript called `REMOTECALL`, and the cookie does not authenticate that call, so `AUTH` is unset.
- The `Authorization` header holds an SDK token, not an access token.
- The application is restricted and the token's user lacks permission, which gives 403. An anonymous call is not stopped by this check and still runs.
- The service or application is inactive, which also gives 403.
**How to confirm**
Inspect the failing request in developer tools and check for an `Authorization` header. Repeat the call with `curl` and a known-good access token. If that works, the service is fine and the browser call is the problem.
**Fix**
Prefer calling the resource server-side from the weblet, as the [minimal app](https://www.zeyos.com/ixml/ixml-guide/development-environment/minimal-app#weblet) does. If the browser must call the service, follow the [design requirements](https://www.zeyos.com/ixml/ixml-guide/development-environment/execution-contexts#calling-your-own-service-from-a-weblet). Do not remove the service's check, and do not treat CORS as the cause or the fix. The response is already open to every origin.
## Wrong include target or type
**Likely causes**
- The identifier is misspelled, or its `.` prefix was dropped.
- The target is a service or weblet, but `include` defaulted to `resource`.
- The target exists locally but has not been deployed. `include` resolves on the instance.
- The script has no app namespace, so `.name` cannot resolve.
**How to confirm**
The error names the type and identifier it looked for, as written in the `include`, for example `Unable to load enhancement "resource:.api" in INCLUDE`. Compare that with the manifest. A compile pass does not check this.
**Fix**
Correct the identifier, push the target, or set the type (**Reference**):
```xml
```
## Already-decoded JSON
**Likely causes**
The value came from an `application/json` resource, which `include` returns decoded. `decode:json` then receives an array instead of a string.
**How to confirm**
Check the resource's `mimetype` in the manifest. Inspect the value with `typeof`:
```xml
```
**Fix**
Delete the `decode:json`. The reverse problem also exists: a JSON **request body** arrives as a string, so read it with `var_body` and decode it inside `try`. See [Includes and JSON resources](https://www.zeyos.com/ixml/ixml-guide/development-environment/execution-contexts#includes-and-json-resources).
## Missing or empty session locale
**Likely causes**
- The code reads `$session.lang`. The locale is in `$session.data.lang` (**Source-confirmed**).
- There is no session user and no valid cookie, as in `TIMING` or `zeysdk run`.
- The code runs in a hook or in `REMOTECALL`, where the result depends on what triggered it. Do not rely on `session` there.
**How to confirm**
Check the context. `session` returns NULL without a session (**Reference**). To check the value on a sandbox, output the named key, such as `$session.data.lang`, from a weblet.
:::warning
Never dump the whole `session` array. It can include credential columns from the user record.
:::
**Fix**
Use `$AUTH.lang` in `REMOTECALL` and always provide a fallback:
```xml
$session.data.lang
en_US
```
## Empty lint selection
**Symptom:** `zeysdk lint` prints `No modified iXML or Zymba files to lint.` and exits `0`.
**Likely causes**
- Nothing differs from the last synchronized state, for example straight after a push.
- The changed script is not registered in the manifest.
**How to confirm**
Run `zeysdk lint --all` and read the file list. Check that your file appears.
**Fix**
Compile the file directly with `zeysdk compile `, or register it. Record an empty selection as **no files checked**, never as a pass.
## Uncertain completion after a timeout
**Symptom:** `Request timed out after 30000ms`, or a dropped connection, during `run` or `push`.
**Likely causes**
The client stopped waiting. That shows nothing about the server, which may have finished, may still be running, or may have stopped. See [Timeouts and uncertain completion](https://www.zeyos.com/ixml/ixml-guide/development-environment/verification-checkpoints#timeouts-and-uncertain-completion).
**How to confirm**
Check the effects directly: records, mail, external systems, and the platform log. After a push, run `zeysdk compare`.
**Fix**
Do not retry blindly. The SDK's request layer does not resend these requests, so a second `run` is a second execution. `zeysdk watch` does retry a failed push on its own, so stop it first. Make long work idempotent and resumable, and move it to a `TIMING` service.
## Text disappears from output
**Symptom:** `