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
Module publish, install, or visibility problems	Registry & permissions	Common module issues
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	Windows service: %ProgramData%\IstariDigital\istari_agent\istari_agent.log. You can also open logs from the Agent system-tray menu.
RHEL / Ubuntu	/opt/local/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 Agent Configuration.

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	%APPDATA%\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.

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:APPDATA\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_*	CLI	Portal URL and API token for downloading agents and modules via stari agent install / stari module install without manual Artifactory URLs. Set with stari client setup-portal.
cli.istari_digital_artifactory_*	CLI	JFrog credentials for Artifactory-based installs. Set with stari client setup-artifactory. The repository path is passed at install time (--repository), not stored here.

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 (registry URL and token) — manually or with stari agent init.

3. Delete istari_agent_id in the Agent installation directory (same folder as the Agent executable):

   OS	Typical path
   Windows	%LOCALAPPDATA%\istari_agent\istari_agent_id (service install: %ProgramFiles%\IstariDigital\istari_agent\)
   RHEL / Ubuntu	/opt/local/istari_agent/istari_agent_id
   macOS	/Applications/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 Starting the Agent — 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. The CLI doesn't write one, but the Agent expects 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

Common module issues

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 your JFrog service account token and stari client setup-artifactory (or equivalent) credentials are correct; obtain tokens from the Istari 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 Tool 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.

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.