06 · Operations

Troubleshooting

Most bridge problems are visible in the runtime state before you reinstall anything. That state covers the SSH (Secure Shell) login, the tunnel, and the daemon inside the Virtuoso CIW (Command Interpreter Window). Read the state, name the failing layer, then take the one action that layer needs. Each section starts from the symptom that the panel or the tool reports.

Triage

The plugin records which layer failed, so the first move is always to read it. Reinstalling the venv is almost never that move. Redeploy the daemon only when the probe says it is missing or of the wrong generation.

SymptomFirst move
Runtime state waitingRun the setupHint load line in the idle CIW.
Runtime state needs-trustConfirm the fingerprint, then start again.
Daemon probe no-listener or legacyDeploy with deploy_daemon, then load its line.
Daemon status auth-failedDeploy the current setup and load it.
A dialog title in the runtime statusAnswer the dialog in Virtuoso, then refresh.
A deployment conflict cardRead the versions, then overwrite only if stale.
Failed to fetch in the browserRetry once, then refresh the DSH page.
History stuck on loadingWait for the local timeout.
A script job that never settlesCheck status with the job id, then cancel.
No CIW block attached to a resultRead the CIW explicitly.
Read the state first

virtuoso_bridge_runtime action status is one call. It reports the state, the daemon condition, the dialog state, the setup hint and the error. Run it before you change anything.

Runtime is waiting

waiting means the SSH login and the tunnel worked, and nothing answers the daemon port yet. The CIW still has to load the prepared setup. The runtime panel shows the exact command, and the status carries it as setupHint. The state flips to running once the health loop sees an answer.

Run in the intended idle CIWSKILL
load("/home/username/.virtuoso-bridge/daemon/virtuoso_setup.il")

After the load, the 20-second health poll flips the runtime to running. A responsive daemon then clears the load hint, so a healthy connection shows no CIW prompt at all.

Don't redeploy for waiting

The tunnel and the SSH session are already correct. Only the CIW side is missing, so redeploying changes nothing.

Host-key trust

needs-trust means the host offered a key you have not trusted yet, and the runtime stays stopped. Confirm the fingerprint, then start again. Host keys and trust shows how the probe labels each key and where the trusted one is written.

A changed key of a type you already trust is different. It is a conflict, the plugin never replaces it, and you remove the stale entry with ssh-keygen -R <host> before you retry.

An extra key type is not a conflict

A host can offer several key types while known_hosts holds only some of them. A type that is simply absent is untrusted, not changed, and a host with at least one trusted type still starts.

Daemon failures

A daemon failure is not an SSH failure. Test and test_connection report each layer separately: SSH reachability and authentication, the remote Python interpreter, the scratch root, and whatever answers the configured daemon port. They work even when no runtime is running.

No listener or legacy

no-listener means nothing listens on the configured port. legacy means another generation of the bridge answers there, usually an old bundle on a different port. Neither is reused. Daemon deployment covers the deploy-and-load sequence.

A restart is not a deploy

A reconnect or a plain restart does not deploy files. Run virtuoso_bridge_runtime action deploy_daemon, then load its returned line in the intended idle CIW.

Auth failed

auth-failed means a bridge daemon is present but rejects this client token. It may predate token authentication, belong to another account, or have had its token rotated. The remedy matches a missing setup: deploy the current setup and load it in the intended CIW.

Blocked by a dialog

A modal dialog can block the daemon while Virtuoso is healthy. The status carries the dialog title, the panel shows a warning, and the hint tells you to click or answer the dialog, then refresh. It never asks for a daemon reinstall or a setup reload. When the probe already says no-listener, dialog inspection is skipped, because no dialog can be the cause.

Daemon lost

If a daemon was healthy and then stops answering, the panel reports a daemon-lost reason instead of the initial setup hint. The setup did load once, so look at the CIW: a busy command, a crashed session, or a changed port.

Shared setup

A shared daemonSetup installed with virtuoso-bridge install-daemon is read-only to clients, and a client environment change cannot retroactively update a running CIW. Daemon deployment covers how clients share it.

Deployment conflict

A normal deploy never overwrites a differing remote bundle. The card reports the versions (otherwise version unknown) and the backend conflict details, and Conflicts explains the comparison.

Overwrite only when the generated bundle is stale or corrupt, or when the profile changed. The old bundle is kept as a backup. After an overwrite, load the newly returned setup line, or call deploy_daemon with replace: true.

A timeout is not a failed deploy

Deployment runs over SSH and can outlast the dashboard's status-poll budget. The dashboard keeps the printed setup path and load line visible, so do not retry a deploy because a browser request timed out. Timeouts has the detail.

Browser and history

Failed to fetch

The client retries once after clearing a stale dashboard base or token, applies request timeouts and prefers the current page origin. Refresh the DSH page if the dashboard server restarted. Reload it after upgrading the plugin so the browser uses the current bundle.

History is loading

History content is fetched when you expand it. A local timeout clears the loading state, and a successful fetch shows the code and result. If the backend is unreachable, the failure is reported instead of hanging.

SSH and backends

  • Verify that ssh is on PATH, or choose Paramiko explicitly. Without OpenSSH, the install stops and asks for confirmation before it continues with the Paramiko backend only.
  • For jump hosts and non-standard ports, check the advanced network fields in the connection editor: sshPort, jumpHost, jumpUser, sshProxy and the role-host overrides.
  • Host-key conflicts need an explicit trust decision. See Host-key trust.
  • identityFile writes a per-connection SSH config that includes your own config. Otherwise, authentication uses the system ssh configuration, agent and keys.
  • A local connection (localhost, 127.0.0.1, ::1) skips SSH and uses the local bridge token file, exactly like virtuoso-bridge local mode.
  • Host-key preflight and the SSH test target the primary host. In a split topology, trust the additional role-host keys through your own ssh/known_hosts first.

Paths and scratch root

If the first IL load reports load: can't access file for a ~/... path, a tilde path reached Virtuoso: load() does not expand ~. Use an absolute remoteScratchRoot on the remote account, or keep ~/ in the setting and let the plugin resolve it before any deployment or upload. Deployment and client/IL uploads never pass ~ to load().

Scratch-root conditionWhat happens before deployment
Missing, under the account homeCreated with mode 0700. You get a warning when a sibling path differs only by _ versus -.
Permissive but user-ownedTightened, not rejected.
A symlink, wrong owner, non-directory, or missing path outside the homeIts own actionable error, with an mkdir -p -m 700 hint where that is the remedy.

The deploy result reports configuredScratchRoot, the resolved scratchRoot, scratchCreated/scratchTightened and any warning, so the load path cannot silently disagree with the configured value. A per-connection remoteScratchRoot overrides the global default. The default reaches deployment, discovery, shells and scripts as VB_REMOTE_SCRATCH_ROOT.

Missing CIW block

The CIW block attached to a call or a settled script job is best effort, and it can be absent. A local Windows Virtuoso, a missing /proc or a busy lane all skip capture, and capture never fails a call. When the block is missing or too late, read the CIW explicitly: force the warning port out, then tail the newest session log.

Explicit CIW readPYTHON
client.execute_skill('warn("") getWarn()')
log = client.run_shell_command(
    'set log = `ls -t ~/CDS.log* | head -1` ; tail -n 40 "$log"')
print(log.output)

run_shell_command runs csh in the Virtuoso process environment, so .output holds that command's stdout and stderr. Do not put it in a loop for every call. The automatic block is the cheap path.

The CIW is a shared transcript

The CIW is shared with the human and with other tools, so a captured line may not belong to this call. Use it to find the cause, never as evidence about the result it is attached to. Unchecking Report CIW warnings/errors with results (ciwReport) turns capture off.

Security

  • Host-key trust is explicit, and a changed key is a conflict that is never silently replaced.
  • Creating a connection, or changing its SSH target, is an access grant outside the workspace. Starting it gives the agent shell, Python and SKILL (Cadence's scripting language) on that account. The agent tool asks for approval unless the session has Full access, and a rejected approval is final.
  • Daemon tokens live in DSH credentials and reach the sidecar through its environment. The token field is write-only, and the panels never return it.
  • The dashboard bootstraps a per-process token over a loopback-only endpoint and rejects cross-site requests.
  • Remote setup paths are private and ownership-checked by virtuoso-bridge-lite.
  • Clients cannot replace a shared install-daemon setup.
Don't work around a refusal

A rejected approval is a decision, not a bug. Create the connection from the configuration page instead of retrying the tool call.

Limits

LimitConsequence
SKILL cannot be loaded into a running CIW automaticallyThe printed load("...") line is a human step. After it, the runtime becomes running on its own.
No Cadence or Spectre license or hardware is includedLive SKILL, Maestro and simulation behaviour depend on the installed bridge, the SSH configuration and the CIW state.
First install downloads Python dependenciesIt needs a package index. Reinstall or repair after changing the Python interpreter or the local repo.
UI rendering depends on the DSH version and themePanels are verified through client registration and source checks, not pixel by pixel.

Reporting a bug

Collect the fields the runtime already records before you open an issue. They turn a guess into a diagnosis.

FieldWhere it appears
StageThe failure stage in the runtime details and tool error.
SSH backendOpenSSH or Paramiko, plus the SSH port.
Daemon stateThe daemon chip, daemonProbe verdict and dialog inspection.
Error code and hinterrorCode, path and hint from a failed deploy or start.

Report at the repository issue tracker. Remove tokens, real host names, account names and private home paths from anything you paste. The project's release guard rejects exactly that kind of data.

Next

That closes the guide. The overview links every chapter and the canonical Markdown sources.