Troubleshooting Istari Digital integration

This page helps you diagnose issues that span the Istari Digital Agent, modules, and integrations. Start with the Agent logs and configuration checks — they surface the cause of most problems. For symptoms tied to a single tool, see the Troubleshooting section on that tool's integration page.

Quick start

Use this table to jump to the right section for your symptom:

Symptom	Where to look	Next steps
Agent crashes or errors on startup	Agent log	Where to find logs, then Verifying istari_digital_config.yaml
Authentication errors, or stari client ping fails	Config file values	Verifying istari_digital_config.yaml
404 Not Found / ID Not Found after moving to a new registry	istari_agent_id file	After changing registry URL or redeploying
Want to confirm the Agent can run jobs end-to-end	Diagnostics	Running Agent diagnostics
Agent is idle and not running jobs	Module versions / tenancy	Common Agent issues
Agent service starts and exits within seconds	Config file ownership	Agent exits cleanly a few seconds after starting
Jobs fail with Permission denied: '/run/user/<uid>'	Linux service account	Jobs fail with Permission denied
Permission denied on the Agent's credentials file	Install ownership	Permission denied on the Agent's credentials file
Not sure which ID a command or screen wants	Agent identifiers	Which identifier is which
Agent authenticates, then registration returns 403	Agent identity type	Only users of type agent can create agent information
Jobs fail to download files on a proxied host	Proxy / egress	Proxy configuration
Module publish, install, or visibility problems	Registry & permissions	Common module issues
Connect missing, or "integration not configured"	App integration setup	Connect tab missing or "integration not configured"
Job cannot open the project, file, or OID it was pointed at	Metadata pointer / egress	Job cannot reach the third-party app
License, connection, or file-format error for one tool	That tool's page	Tool-specific issues

Where to find logs

The Agent log is the first place to look for errors during startup, job execution, or module loading.

OS	Log file path	Notes
Windows	%LOCALAPPDATA%\istari_agent\istari_agent.log	Per-machine install: %ProgramData%\IstariDigital\istari_agent\istari_agent.log. You can also open logs from the Agent system-tray menu.
RHEL / Ubuntu	~/.local/share/istari_agent/istari_agent.log	After startup, log output is also printed to the terminal.
macOS	~/Library/Application Support/istari_agent/istari_agent.log	Runtime files (identity, modules) live in the same directory — see The files an agent uses.

Log verbosity: Set istari_digital_agent_log_level in istari_digital_config.yaml ("debug", "info", "warning", "error", "critical"; default "info"). See istari_digital_agent_log_level.

Verifying istari_digital_config.yaml

The Agent and the Istari Digital CLI share a single YAML file, istari_digital_config.yaml. Agent startup failures, authentication errors, and CLI client ping failures often trace back to wrong values in this file or a stale agent identity on disk.

Configuration file location

The file lives in the istari_digital configuration directory — not in the Agent install folder:

OS	Path
Windows	%LOCALAPPDATA%\istari_digital\istari_digital_config.yaml
RHEL / Ubuntu	~/.config/istari_digital/istari_digital_config.yaml
macOS	~/Library/Application Support/istari_digital/istari_digital_config.yaml

See Agent Configuration for the full layout, optional keys, and environment-variable overrides, and The files an agent uses for the other files on the host — the credentials file, istari_agent_id, the log, and the modules folder.

Unsure which identifier a command or a screen is asking for — Client ID, Agent ID, Key ID, or the agent's name? Which identifier is which names each one and says where to read it.

Inspect the file

Print the current configuration on the host where the Agent or CLI runs:

# Linux / macOS
cat ~/.config/istari_digital/istari_digital_config.yaml
# macOS (if the file is under Application Support)
cat ~/Library/Application\ Support/istari_digital/istari_digital_config.yaml

# Windows
type $env:LOCALAPPDATA\istari_digital\istari_digital_config.yaml

Confirm YAML indentation (spaces, not tabs), quoted URLs and tokens, and that placeholder values such as replace-with-registry-service-url have been replaced.

What the sections mean

A typical file combines up to three top-level sections:

default: {}

agent:
  istari_digital_agent_registry_api_url: "https://registry.example.istari.digital"
  istari_digital_agent_registry_api_token: "agent-personal-access-token"

cli:
  istari_digital_registry_url: "https://registry.example.istari.digital"
  istari_digital_registry_auth_token: "user-personal-access-token"
  istari_digital_customer_portal_url: "https://portal.istari.app"
  istari_digital_customer_portal_auth_token: "portal-api-token"
  istari_digital_artifactory_url: "https://istaridigital.jfrog.io/artifactory"
  istari_digital_artifactory_username: "service-account"
  istari_digital_artifactory_password: "jfrog-token"

Section / key	Used by	Purpose
default	Agent	Must be present (can be {}). The Agent errors with KeyError: 'default' if this section is missing — see Common Agent issues below.
agent.istari_digital_agent_registry_api_url	Agent	Registry service URL the Agent connects to. Copy from Settings → Developer Settings → Registry Information in the platform. Usually https://registry.<your-host>.
agent.istari_digital_agent_registry_api_token	Agent	Agent Personal Access Token. Created by an administrator — see Generate an Agent token. Not the same as a user PAT.
cli.istari_digital_registry_url	CLI	Registry URL for module publish, list, and deprecate commands (stari client …). Same host as the Agent URL in most deployments.
cli.istari_digital_registry_auth_token	CLI	User Personal Access Token — see Developer Settings. Used by stari client init, stari client ping, and publish workflows.
cli.istari_digital_customer_portal_url	CLI	Customer Portal backend API URL, shown on the portal's Organization Access Tokens page. Set with stari client setup-portal.
cli.istari_digital_customer_portal_auth_token	CLI	Customer Portal organization access token. Required by stari agent install and stari module install unless you pass --local-file — see Connect the CLI to the Customer Portal.

Use stari client ping to verify CLI registry credentials, and check the Agent log after restart to confirm the Agent loaded the agent section.

After changing registry URL or redeploying

When you point an Agent at a new registry (new deployment, new tenant, or recovered environment), updating istari_digital_config.yaml alone is not enough. The Agent stores its platform identity in an istari_agent_id file on disk. If that file still references the old registry, you may see 404 Not Found or ID Not Found errors during registration.

1. Stop the Agent.

2. Update the agent section with the new platform URL and credentials.

3. Delete istari_agent_id from the Agent's support directory — the path below for your platform, which is the folder holding the Agent executable on some installs but not all:

   OS	Typical path
   Windows	%LOCALAPPDATA%\istari_agent\istari_agent_id (per-machine install: %ProgramData%\IstariDigital\istari_agent\istari_agent_id)
   RHEL / Ubuntu	~/.local/share/istari_agent/istari_agent_id (package installs: /opt/local/istari_agent/istari_agent_id)
   macOS	~/Library/Application Support/istari_agent/istari_agent_id

4. Restart the Agent. It registers as a new Agent record in the platform.

See October 2025 — Changes to Agent tracking for the background and example log errors.

Running Agent diagnostics

Starting with Agent v9.4.0, you can use the Agent's diagnostics to test and validate the following Agent functionalities:

• Ability to receive an assigned job from the Istari Digital Platform
• Ability to run an assigned job (handling successful and failed jobs)
• Ability to upload the results to the Istari Digital Platform
• Ability to return to IDLE state, ready for additional jobs

Right-click "Run Diagnostics" in the system tray to start the test.

Note: When prompted, you must provide a human personal access token. The diagnostics will not work with an agent token.

Once completed, a message will pop up with the result of the test. Navigate to the Istari Digital Platform to look at the two models uploaded by the diagnostics thread and their associated jobs. Additional information is available in the Agent logs.

See Run the agent's diagnostics for screenshots and the full walkthrough.

Common Agent issues

Agent isn't picking up jobs

Symptom: An Agent stays idle and does not run assigned jobs.

Cause: Agents across tenants have the same module installed, but at different versions.

Solution:

1. Update the module on every agent so they all run the latest version published to the Istari Digital Platform.
2. For tenant-scoped agents, see Agent Multi-Tenancy.

DisplayNameError: Bad display name ""

Symptom: The Agent crashes on startup with DisplayNameError: Bad display name "".

Cause: The Agent tries to start a system-tray icon, which requires a graphical display. In Docker or over SSH (headless), there is no display.

Solution:

1. Enable headless mode by adding the following under agent: in istari_digital_config.yaml:

   agent:
     istari_digital_agent_headless_mode: true

2. Restart the Agent. See istari_digital_agent_headless_mode in Agent Configuration.

KeyError: 'default'

Symptom: The Agent fails to start with KeyError: 'default'.

Cause: The configuration file has no default section. It is easy to leave out when writing the file by hand, and the Agent will not start without it.

Solution: Append an empty default section to istari_digital_config.yaml (adjust the path for your OS — see Configuration file location):

echo "default: {}" >> ~/.config/istari_digital/istari_digital_config.yaml

Agent exits cleanly a few seconds after starting

Symptom: systemctl status istari-agent reports Active: inactive (dead) with code=exited, status=0/SUCCESS shortly after Started istari-agent.service, and the journal shows no application output. The Agent log contains:

No config found at /root/.config/istari_digital. A default one has been created. User must update required values.

Cause: The configuration was written under one account and the Agent runs as another. The file sits in the operator's home directory, while the service — running as root, or as whatever User= names — looks under its own home, finds nothing, writes a placeholder configuration, and exits.

Solution:

1. Stop the service: sudo systemctl stop istari-agent.
2. Write the configuration in the home directory of the account the service runs as, overwriting the placeholder the Agent left there — /root/.config/istari_digital/istari_digital_config.yaml for a unit with no User=. Copy the credentials file somewhere that account can read, and name that path in the configuration.
3. Confirm no placeholders remain: sudo grep 'replace-with-' /root/.config/istari_digital/istari_digital_config.yaml should return nothing.
4. Start the service and watch the log for Loading local modules.

Alternatively, set User= in the unit to the account whose configuration you already wrote. See Which user owns the configuration.

On Windows, the same failure follows an install for a different operating account. On a per-machine install the installer seeds the configuration into the profile of whoever ran it, so an operator who is a different account starts an Agent that finds no configuration, writes a placeholder file under its own %LOCALAPPDATA%\istari_digital\, and exits. The operator writes their own istari_digital_config.yaml as themselves; see If a different account will operate the agent.

Permission denied on the Agent's credentials file

Symptom: The Agent logs a permission error reading its credentials file and never authenticates, or a sudo-started Agent leaves files the same Agent cannot rewrite when started normally later.

Cause: The credentials file, the configuration, and the Agent's data directory each belong to whichever account created them. A file created by root, or by an administrator's login, is not readable by the service account the Agent runs as — the credentials file in particular should stay readable by that account only.

Solution: Put both files under the account that runs the Agent, and start the Agent as that account:

mkdir -p ~/.istari_digital
mv /PATH/TO/agent-credentials-<key id>.json ~/.istari_digital/
chmod 600 ~/.istari_digital/agent-credentials-<key id>.json

Then point istari_digital_agent_identity_service_secret_file at that path in the configuration file for the same account.

If an earlier sudo run created the Agent's data directory as root, hand it back — sudo chown -R "$(id -un)" ~/Library/Application\ Support/istari_agent on macOS, or the equivalent path for your OS.

Registration refused: Only users of type agent can create agent information

Symptom: The Agent authenticates, then every registration attempt fails with a 403 and the registration thread retries with backoff:

INFO - Authenticated with identity-service (client_id=<client id>, token expires at …)
ERROR - Exception ForbiddenException in method V2Api.register_agent : (403)
HTTP response body: {"detail":"Agent Create Forbidden: \"Only users of type agent can create agent information\""}

Cause: Authentication succeeded — the key is valid and the Identity Service knows this client ID. The refusal comes from the registry, which only lets a user of type agent create an agent record. The registry keeps its own user record for each identity and sets that type the first time the identity calls it, based on what the token says. An identity that arrives as anything else is recorded as a human user, and the type is not corrected on later calls. Registering a key creates the identity in the Identity Service; it does not by itself make the registry treat that identity as an agent.

Solution:

1. Create the agent from the web app: Agents → Generate Key → Download credentials. This path creates the agent along with its key and returns the Client ID the platform assigned.
2. Copy the downloaded file to the host, point istari_digital_agent_identity_service_secret_file at it, and restart the Agent. See Create an agent and its key.
3. Do not reuse the refused client ID. The registry does not change the type of a record it already has, so an identity it once recorded as human keeps failing.
4. If credentials created in the web app hit the same 403, send the Agent log to support@istaridigital.com — the identity is missing its agent role on that deployment, which is not something you can fix from the host.

Registry rejects the Agent: Agent <uuid> is archived

Symptom: The Agent log shows an HTTP error from the registry:

HTTP response body: {"detail":"Method Not Allowed: \"Agent 0d5798bf-… is archived\""}

Cause: The token and registry URL are fine — the Agent record was archived in the platform. The Agent reads its UUID from istari_agent_id on every start, so restarting keeps hitting the same archived record.

Solution: Either restore the Agent from the admin Agents page, or let it register a fresh record: stop the Agent, delete istari_agent_id (see the paths above), and start the Agent again.

Jobs fail with Permission denied: '/run/user/<uid>'

Symptom: The Agent accepts a job and then fails it immediately:

Job <uuid> failed. [Errno 13] Permission denied: '/run/user/1000'

Cause: On Linux, systemd-logind creates /run/user/<uid> for interactive login sessions and removes it at the last logout. An Agent running as a background service has no session, so the directory disappears whenever nobody is logged in. A tell-tale sign: the directory exists when you SSH in to check, but its timestamp is later than the failed job.

Solution: Enable lingering for the service account so the runtime directory is created at boot and persists:

sudo loginctl enable-linger <user>
loginctl show-user <user> | grep -E 'Linger|RuntimePath'
sudo systemctl restart istari-agent

Common module issues

Module missing from the Agent log at startup

Symptom: After restarting the Agent, Loading local modules appears but your module is not listed, so its functions never run.

Cause: The Agent skips module directories it cannot load.

Solution: On the Agent host, check that:

1. The module directory under istari_modules/ contains a module_manifest.json, and that it is valid JSON.
2. Where the module ships a binary, the binary is present and executable.
3. The manifest's operating_systems array includes the host OS, for example "Ubuntu 24.04" or "macOS 15".
4. If you replaced files in a module the agent had already loaded, the agent was restarted afterwards — adding a new folder does not need a restart. See Module lifecycle on the agent.

Module version 1.0.0 already exists

Symptom: Publishing fails with:

HTTP response body: {"detail":"Malformed Manifest: \"Module version 1.0.0 already exists.\""}

Cause: That exact version was already uploaded. Module versions are immutable once published.

Solution: Bump module_version in module_manifest.json (e.g. 1.0.0 → 1.0.1) and publish again.

Module tool X does not match manifest tool Y

Symptom: Publishing a new version fails because the tool name doesn't match the published module.

Cause: The platform binds the tool name to the module_key on first publish. You changed the tool field for an existing module_key.

Solution: Either revert the tool field to the original value, or use a new module_key for the renamed tool.

Module not found in the CLI

Symptom: The CLI returns an error stating the module doesn't exist.

Cause: The module may not be published to the registry yet, or your credentials do not have access.

Solution:

1. Verify you're using CLI version 0.21.1 or higher: stari --version.
2. Confirm the host's Customer Portal credentials are set and current — re-run stari client setup-portal with a token generated from the Customer Portal if needed.
3. Confirm the module version is listed under modules in the portal Assets view for your release.

Users can't see a module in the UI

Symptom: Users report a module doesn't appear in the Tool Name dropdown.

Cause: Permissions haven't been granted for the module.

Solution:

1. Grant users access from the Admin panel — see Managing module function access.
2. Ask users to refresh their browser (hard refresh: Ctrl+Shift+R or Cmd+Shift+R).
3. Verify the module is installed on the appropriate agent machine.

ModuleNotFoundError: No module named 'module'

Symptom: Running the module raises ModuleNotFoundError: No module named 'module'.

Cause: Python is running from outside the project directory, or Poetry's virtual environment is not active.

Solution: Run from the module's project directory using poetry run.

PyInstaller build fails with missing Python.h

Symptom: The PyInstaller build fails with a missing Python.h error.

Cause: Python development headers are not installed in the build container.

Solution:

1. Install the headers inside the container:

   apt-get install -y python3.12-dev

2. The Integration 302 tutorial Dockerfile already includes libpython3.12; add this only if you use a different base image.

Configuration not being applied to a module

Symptom: A module doesn't use the configured installation directory, executable path, or other module-specific value.

Cause: Configuration file in the wrong location, syntax errors, or deprecated variable names.

Solution:

1. Verify istari_digital_config.yaml is in the correct location and contains expected values — see Verifying istari_digital_config.yaml.
2. Check YAML syntax (proper indentation, no tabs, correct nesting).
3. Use the new standardized variable names introduced in istari-agent 9.8.0 — see istari_digital_agent_module_configurations.
4. Restart the Istari Digital Agent after configuration changes.
5. Check Agent logs to confirm the configuration is being loaded.

Connected resource issues

These apply to Resources that live in a third-party app and are registered with a metadata pointer file rather than uploaded. See Connected resources for the Python Client flow.

Connect tab missing or "integration not configured"

Symptom: Resources → Add resources → Connect does not list an integration (for example Teamwork Cloud), or the connect flow fails at setup.

Cause: No app integration for that application on the tenant.

Solution:

1. An administrator connects the application under App Integrations, with the correct type and any app-specific fields (for Teamwork Cloud, server_name). See App Integrations.
2. Confirm at least one credential exists for it — a shared service account, or a linked account for the user running the job.
3. Registering from the Python Client with add_model and a metadata pointer file does not need the Connect UI, but running a job on the Resource still needs a credential to bind. See Run jobs on a third-party Resource.

Job cannot reach the third-party app

Symptom: The job is assigned and starts, but the module cannot open the project, file, or OID named in the metadata pointer file.

Cause: Wrong fields in the metadata JSON, a missing server_name with no agent-side default, an incorrectly encoded Windchill OID, or no network route from the agent host to the third-party app.

Solution:

1. Compare your metadata file against the integration's page — for Teamwork Cloud, Dassault Cameo.
2. Set dassault_cameo_teamwork_cloud_server_name on the agent if you omit server_name from the pointer file. See that module's Installation section.
3. For Windchill, URL-decode the oid in .istari_windchill_metadata (%3A → :, %2F → /).
4. Confirm the agent host can reach the PLM or cloud host on the required ports. On a proxied host, see Proxy configuration.

Tool-specific issues

For symptoms specific to a particular integration — license, connection, model loading, parameter updates — see the Troubleshooting section on that integration's page. Each tool page lists common symptoms, causes, and solutions for that tool.

See Integrations for the full list of supported tools.

Before contacting support

Work through these checks first — they resolve most issues and help support diagnose the rest faster:

• Check the Agent log for error messages — see Where to find logs.
• Verify istari_digital_config.yaml values and location — see Verifying istari_digital_config.yaml.
• Confirm the module is installed and configured on the right agent — see Module Installation.
• For a single-tool symptom, check that tool's Troubleshooting section.

Still stuck? Contact your Istari Digital support representative or email support@istaridigital.com.