23 Common development issues

23.1 Where can I find my Tercen token?

You can find your Tercen token by logging into your instance and navigating to:

https://YOUR_INSTANCE_URL/_token

For example: - If you work on tercen.com, go to: https://tercen.com/_token - If you work on a custom instance, replace YOUR_INSTANCE_URL with your actual domain

The token will be displayed on this page and can be copied for use in your development environment.

23.2 Failed to decode

tercen.http.HttpClientService.TercenError: unknown : failed to decode

When running the TercenContext() function in Python (or tercenCtx() in R), this error happens when it is not possible to retrieve data from the specified data step. Common underlying reasons include: * Data Step has not been saved * Data Step is already run

In order to fix the issue: * Reset the data step, * Save - Refresh - Save the data step, * Re-run the TercenContext call.

23.3 My operator doesn’t appear in the picker / library

You added your operator’s Git repository to a library, the clone succeeded, but the operator never shows up when you search for it in a data step’s operator picker.

“Add from Git” only installs a searchable operator (registers the operator record the picker searches) when all of the following hold. If any fails, the repository’s files are copied but no operator is registered — usually with no obvious error:

The repository name ends in _operator. This is the gate that triggers operator installation. uka_analysis → not installed; uka_analysis_operator → installed. (This is the most common cause.)
The repository is in a trusted organization. Managed instances only trust repositories under approved GitHub organizations (commonly github.com/tercen/ and github.com/pamgene/). Repositories under a personal account or an untrusted organization fail with tercen.forbidden.untrusted.git. Ask your Tercen admin which organizations are trusted.
All names are lowercase. Docker/OCI image names must be lowercase; an uppercase repository or image name (e.g. My_Operator) breaks the container build/pull, so no operator is registered.
The operator was installed, not just cloned. Cloning a project copies files; it is the install step (gated by points 1–3) that creates the searchable operator record.

Checklist

Repository name ends in _operator and is entirely lowercase
Repository lives under a trusted organization
The container image built successfully and is pullable
You selected the correct source library in the picker

Tip

To make a fork or renamed variant installable, rename the repository to a lowercase name ending in _operator (e.g. my_variant_operator) under a trusted organization, then add it to the library again.

23.4 I pushed a fix but the operator still runs the old code

You committed a fix, rebuilt, and the step behaves exactly as before — same output, same error, no sign your change took effect.

The usual cause is a reused version identifier. Check which of these applies:

You moved a git tag. If you deleted and re-pushed a tag (e.g. 0.0.3) so it points at a new commit, already-installed instances will not pick up the new commit. Tercen resolves a version to a commit at first install, stores the operator in a directory named after that commit, and on later runs skips the download when that directory already exists — so the tag is never re-resolved. Fix: release a new version (0.0.4) and repoint the step at it.
Your container points at a mutable image tag. With :main or :master, the image that gets pulled depends on what was built last, and a cached image may not be re-pulled at all. Fix: use an immutable versioned tag (:0.0.4).
The step is pinned to an older version than you think. Open the step’s operator settings and confirm the exact version string it references — a workflow keeps whatever version it was configured with, and does not follow later releases.

This failure is silent by design

There is no error for any of the above — the operator runs successfully, just not the code you expected. If you need to confirm which commit is actually running, add a temporary log line containing the version (e.g. message("operator version 0.0.4")) and release it under a new version number. If the line doesn’t appear, the old install is still being used.

See Pin an immutable version tag and the tagging guidance in the same chapter.

# Common development issues ## Where can I find my Tercen token? You can find your Tercen token by logging into your instance and navigating to: `https://YOUR_INSTANCE_URL/_token` For example: - If you work on tercen.com, go to: `https://tercen.com/_token` - If you work on a custom instance, replace `YOUR_INSTANCE_URL` with your actual domain The token will be displayed on this page and can be copied for use in your development environment. ## Failed to decode ``` tercen.http.HttpClientService.TercenError: unknown : failed to decode ``` When running the `TercenContext()` function in Python (or `tercenCtx()` in R), this error happens when it is not possible to retrieve data from the specified data step. Common underlying reasons include: * Data Step has not been saved * Data Step is already run In order to fix the issue: * Reset the data step, * Save - Refresh - Save the data step, * Re-run the TercenContext call. ## My operator doesn't appear in the picker / library You added your operator's Git repository to a library, the clone succeeded, but the operator never shows up when you search for it in a data step's operator picker. "Add from Git" only **installs** a searchable operator (registers the operator record the picker searches) when *all* of the following hold. If any fails, the repository's files are copied but no operator is registered — usually with no obvious error: 1. **The repository name ends in `_operator`.** This is the gate that triggers operator installation. `uka_analysis` → not installed; `uka_analysis_operator` → installed. *(This is the most common cause.)* 2. **The repository is in a trusted organization.** Managed instances only trust repositories under approved GitHub organizations (commonly `github.com/tercen/` and `github.com/pamgene/`). Repositories under a personal account or an untrusted organization fail with `tercen.forbidden.untrusted.git`. Ask your Tercen admin which organizations are trusted. 3. **All names are lowercase.** Docker/OCI image names must be lowercase; an uppercase repository or image name (e.g. `My_Operator`) breaks the container build/pull, so no operator is registered. 4. **The operator was installed, not just cloned.** Cloning a project copies files; it is the install step (gated by points 1–3) that creates the searchable operator record. **Checklist** - [ ] Repository name ends in `_operator` and is entirely lowercase - [ ] Repository lives under a trusted organization - [ ] The container image built successfully and is pullable - [ ] You selected the correct **source library** in the picker ::: {.callout-tip} To make a fork or renamed variant installable, rename the repository to a lowercase name ending in `_operator` (e.g. `my_variant_operator`) under a trusted organization, then add it to the library again. ::: ## I pushed a fix but the operator still runs the old code You committed a fix, rebuilt, and the step behaves exactly as before — same output, same error, no sign your change took effect. **The usual cause is a reused version identifier.** Check which of these applies: 1. **You moved a git tag.** If you deleted and re-pushed a tag (e.g. `0.0.3`) so it points at a new commit, already-installed instances will **not** pick up the new commit. Tercen resolves a version to a commit at first install, stores the operator in a directory named after that commit, and on later runs skips the download when that directory already exists — so the tag is never re-resolved. **Fix:** release a new version (`0.0.4`) and repoint the step at it. 2. **Your `container` points at a mutable image tag.** With `:main` or `:master`, the image that gets pulled depends on what was built last, and a cached image may not be re-pulled at all. **Fix:** use an immutable versioned tag (`:0.0.4`). 3. **The step is pinned to an older version than you think.** Open the step's operator settings and confirm the exact version string it references — a workflow keeps whatever version it was configured with, and does not follow later releases. ::: {.callout-note} ## This failure is silent by design There is no error for any of the above — the operator runs successfully, just not the code you expected. If you need to confirm *which* commit is actually running, add a temporary log line containing the version (e.g. `message("operator version 0.0.4")`) and release it under a **new** version number. If the line doesn't appear, the old install is still being used. ::: See [Pin an immutable version tag](../02-operator-development/8-ci.qmd) and the tagging guidance in the same chapter.