> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/developers-guides/scripting/troubleshooting.md).

# Troubleshooting scripts

Symptom, cause and fix tables for scripts that do not run, fail at save, return ignored values or break a pass render, with the platform's log messages.

A script problem is nearly always one of a few causes: the file was not loaded, the key or the id does not match, a handler name has the wrong case, a returned key has the wrong case, a JavaScript error in one file affects every script, or the remote system failed in a way the script did not expect. This page starts from what is observed, a screen, a message or a missing value, and leads to the cause and the fix. Messages quoted here are the ones the platform really writes, so they can be searched for in the logs or in a save error.

Script messages appear in **Settings → Monitoring → Logs**; see [Utility globals](https://docs.thewalletcrew.io/developers-guides/scripting/globals/tools.md#console). The general rules behind the table are in [How scripts run](https://docs.thewalletcrew.io/developers-guides/scripting/how-scripts-run.md) and [Handlers](https://docs.thewalletcrew.io/developers-guides/scripting/handlers.md).

<details>

<summary><strong>Real-world examples</strong></summary>

* A data provider "does nothing": the `scriptId` in the pass type has a different spelling than the last part of the registration key.
* All scripts of a tenant fail after an edit: one file has a syntax error.
* A pass updater returns `{ passType: 'x' }` and nothing changes: the member is `PassType`.
* A pass cannot be displayed: `Fill` throws when the remote system is down.

</details>

## Saving the configuration

| Symptom                                                                                                                                | Cause                                                                                                                                                                                         | Fix                                                                                                                                |
| -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Save refused with `Error while executing file server/scripts/<file> - ...`                                                             | The file has a syntax error, or its top-level code or its default export threw. The message ends with the reason from the engine                                                              | Fix the file named in the message. When several files are listed, fix each                                                         |
| Save refused with `server/passes/<passType>.yml: dataProviders[<n>].scriptId: A script entry needs the scriptId of the tenant script.` | An entry with `provider: script` has no `scriptId`                                                                                                                                            | Add `scriptId`                                                                                                                     |
| Save refused with `... dataProviders[<n>].provider: '<name>' is not an available data provider. ...`                                   | The `provider` is not `script` and not the name of a published provider                                                                                                                       | Use `script`, or one of the names listed in the message                                                                            |
| Save refused with a message about the namespace of a script                                                                            | The namespace returned by `Describe` (or the script id when none is returned) is not readable by a template, belongs to the platform, or is also used by another script of the same pass type | Return another `namespace` from `Describe`: letters, digits and underscores separated by dots, not starting a segment with a digit |
| Save accepted but the script does nothing                                                                                              | Save does not check that a `scriptId` has a registration, nor that handlers exist                                                                                                             | Run the real flow once and look at the pass data page                                                                              |

## The script is never called

| Symptom                                                                          | Cause                                                                                                                                                | Fix                                                                                                   |
| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Nothing happens and no message is logged                                         | The file name does not end in lowercase `.js`, or the file is not under `server/scripts/`                                                            | Rename or move the file                                                                               |
| Warning `file <path> doesn't export default function`                            | The file has no `export default function (context)`                                                                                                  | Add the default export that calls `context.register`                                                  |
| A pass data provider appears as found, with no variable                          | The registration key does not match the `scriptId`, so the platform finds no script and does nothing                                                 | Compare the last segment of the key with `scriptId` letter by letter; keys and ids are case-sensitive |
| A flow step does nothing                                                         | The `scriptId` of the step has no `runtime.scriptable.customerPipelineElement.<scriptId>` registration, or the handler is not named `CreateOrUpdate` | Fix the id and the handler name. A missing `CreateOrUpdate` is a silent no-op                         |
| The behavior of a script does not match its file                                 | Another file registers the same key, and the last registration wins; the order of files is not defined                                               | Search every file for the key and keep one                                                            |
| A scheduler task does nothing                                                    | Log message `wallet.scriptablePushUpdates refused, no pass was updated: settings.scriptName '<name>' does not exist.`                                | Set `settings.scriptName` to the id used in `runtime.scriptable.pushUpdates.<id>`                     |
| The scheduled task runs and updates nothing                                      | `GetPasses` returned no `PassInformations`, or the log shows `Found 0 pass informations to update`                                                   | Check the query of the script and the shape of the returned object                                    |
| No email is sent through the script engine, no error                             | `SendEmail` is missing; a missing handler on this endpoint is a silent no-op                                                                         | Register `SendEmail`                                                                                  |
| Every email fails with `endpoint 'runtime.scriptable.emailEngine not registered` | The email provider is `script`, but no file registers the key                                                                                        | Register `runtime.scriptable.emailEngine` in one file                                                 |

## The script runs but the result is ignored

| Symptom                                                               | Cause                                                                                                                                                      | Fix                                                                                                                                                                                               |
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The returned object has no effect, no error                           | The keys have the wrong case. Returned objects are converted by exact member name; unknown names are dropped                                               | Use PascalCase for types without script names (`PassType`, `Identifiers`, `PassInformations`, `Throughput`) and camelCase for those with script names (`Describe`, benefits, Apple pass resolver) |
| A date is wrong by hours, a day or a month                            | A `Date` built from its parts depends on the server time zone, and months start at 0                                                                       | Return an ISO 8601 string with an offset, such as `2026-03-01T10:00:00Z`                                                                                                                          |
| `device` never matches `'apple'` or `'google'`                        | `device` is a number: `0` for Apple, `2` for Google                                                                                                        | Compare with numbers                                                                                                                                                                              |
| A number is missing from the entity                                   | The value was `NaN` or infinite; the platform removed the key and logged `A script assigned the non-finite number <value> to '<key>'; the key was dropped` | Check the value with the global `isFinite` before assigning                                                                                                                                       |
| A key cannot be removed                                               | Assigning an empty string keeps the key                                                                                                                    | Assign `null`                                                                                                                                                                                     |
| `OnPassCreating` wiped the identifiers                                | The hook returned `Identifiers: {}`, which replaces all identifiers                                                                                        | Return `Identifiers` only with the full new set, otherwise `null`                                                                                                                                 |
| The pass type is not changed by `OnPassCreating`                      | `PassType` is empty or missing, or the hook returned a lowercase `passType`                                                                                | Return a non-empty `PassType`                                                                                                                                                                     |
| A `MapTo...` hook of an extension has no effect                       | The returned or changed member has the wrong casing for its type; connector objects keep their .NET member names                                           | See [Connector scripts](https://docs.thewalletcrew.io/developers-guides/scripting/extensions.md#member-names-inside-connector-objects)                                                            |
| An extension hook is never called                                     | The key is not `extensions.<connector>...`, the slot file name differs, or the connector is not configured                                                 | See [Connector scripts](https://docs.thewalletcrew.io/developers-guides/scripting/extensions.md#script-slots-and-file-names)                                                                      |
| `Describe` returns a promise and the admin console shows no variables | `Describe` must be synchronous                                                                                                                             | Remove `async` and `await` from `Describe`                                                                                                                                                        |

## The pass cannot be displayed or the request fails

| Symptom                                                                                                          | Cause                                                                                                      | Fix                                                                                                                                                                                               |
| ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The pass render fails, the data page shows the provider as failed with "The tenant script failed."               | `Fill` threw, often from `fetch` on a non-2xx response, a network error or a `JSON.parse` of an empty body | Catch the failure in `Fill`, write a specific error key (such as `lookupError`) and return `false`. See [First script](https://docs.thewalletcrew.io/developers-guides/scripting/first-script.md) |
| The data page shows the provider as failed with "The provider did not answer in time." or "could not be reached" | The remote system is slow or unreachable                                                                   | Add a cache, keep the call short, and handle the failure in the script                                                                                                                            |
| Error `method Fill missing`, or the same message with another method name                                        | The handler is registered under another name. The match is exact and case-sensitive                        | Use the exact method name as the property name                                                                                                                                                    |
| A JSON syntax error thrown by `JSON.parse`                                                                       | The response was empty or not JSON, usually after `ThrowOnError: false` with an error status               | Check `StatusCode` first, then parse inside `try` / `catch`                                                                                                                                       |
| All scripts fail together, after an edit                                                                         | A JavaScript error in any file makes the loader fail for the whole tenant                                  | Fix the file named in `Error while executing file ...`                                                                                                                                            |
| Error `A script handler ran for more than 5000 ms without returning` (`TimeoutException`)                        | A handler ran synchronously, before its first `await`, for more than 5000 ms                               | Avoid long loops before the first `await`; see [How scripts run](https://docs.thewalletcrew.io/developers-guides/scripting/how-scripts-run.md#time-limits)                                        |

Problems with `fetch` itself (non-2xx errors, cache keys, retries and repeated POSTs, refused addresses) are collected in the [fetch errors and edge cases](https://docs.thewalletcrew.io/developers-guides/scripting/globals/fetch.md#errors-and-edge-cases) and the pages [fetch authentication](https://docs.thewalletcrew.io/developers-guides/scripting/globals/fetch/fetch-authentication.md) and [fetch cache and throttle](https://docs.thewalletcrew.io/developers-guides/scripting/globals/fetch/fetch-cache-and-throttle.md).

## Secrets

| Symptom                                                                  | Cause                                                                                 | Fix                                                                  |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `getSecret` throws an error about the key                                | The key is not 2 to 32 characters among letters, digits and hyphens                   | Rename the secret                                                    |
| `getSecret` returns `null`, with the warning `key <key> does not exists` | No secret of that exact name, a different case, or no enabled and non-expired version | Check the name in the admin console and the validity of its versions |
| A new value of a secret is not used yet                                  | Results, a missing secret included, are cached for up to ten minutes                  | Wait, or rely on a new secret name for an immediate change           |

## Deprecation warnings

| Symptom                                                                                                      | Cause                                                   | Fix                                           |
| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- | --------------------------------------------- |
| Warning `Tenant <id>: the script endpoint <key> is obsolete and still runs. Register <replacement> instead.` | An obsolete endpoint name is registered; it still works | Register the replacement named in the message |
| An `import` from `neo/secrets` logs a warning                                                                | The obsolete module name; it still works                | Import from `twc/secrets`                     |

The legacy names are cataloged on [Obsolete neostore names](https://docs.thewalletcrew.io/developers-guides/scripting/modules/obsolete-neo-names.md). The prefix `neostore` is the platform's former name and is kept in technical identifiers.

## Pass updater and install hooks

| Symptom                                                                                                                    | Cause                                                                                                | Fix                                                                                                                                                                                                                                                             |
| -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Log message `An error has occured while executing script for pass event <event>. This script has been ignored - <message>` | A hook threw. The error is logged, this script is skipped for the event, and the operation continues | Fix the error in the hook; the message shows its text                                                                                                                                                                                                           |
| The CRM is updated on every install                                                                                        | The hook ignores the registration counts in `additionalInformation.registrationInformation`          | For a pass installed on one device, `activeRegistrationCount` goes from 1 on the install to 0 on the uninstall and back to 1 on a reinstall, while `totalRegistrationCount` never decreases: 1 on the install, still 1 after the uninstall, 2 after a reinstall |
| Two scripts both change the pass type                                                                                      | All registered pass updaters run                                                                     | Keep the rule in one script                                                                                                                                                                                                                                     |

## Checking quickly

1. Open the pass data page of a pass: it lists each data provider with its outcome, duration and variables, and "Refresh data" runs them again.
2. Search the configuration history for the last change to `server/scripts/`.
3. Search for the registration key across all script files to find duplicates.
4. Look up the messages above in **Settings → Monitoring → Logs**.

## FAQ

<details>

<summary><strong>A script worked yesterday and fails today without a change. Why?</strong></summary>

The remote system, the secret or the data changed. A secret version expiring makes `getSecret` return `null`; a remote system that started answering with another status or an empty body breaks a parse that did not check the status. The data page of a pass shows which provider failed, and the configuration history shows whether anything changed in the tenant.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thewalletcrew.io/developers-guides/scripting/troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
