Adapter diagnostics

An adapter that will not connect, or a method that never answers, is debugged from two ends: what your process does, and what the desktop observed. This page covers both, and what the built-in diagnostics do and do not record.

Symptoms

• The connection never becomes ready. The workspace reports that the adapter could not start, or that initialization failed.
• A capability is missing. Files, Terminal or Remote settings are unavailable even though the adapter is connected.
• Individual calls fail with unavailable, busy or deadline, while the connection stays up.
• The connection drops during use, and everything in flight fails with closed.
• Cleanup is unconfirmed after disconnecting, and the desktop keeps the package reserved.

Checks

Validate the package

shellcanvas-adapter validate ./my-device-package/adapter.json

This re-hashes every declared file and executes nothing. It catches a stale package, a modified binary and a manifest that no longer matches what you built.

Read the connection diagnostics

Open App Manager → Connection adapters → Connection diagnostics, pick the connection, and use Refresh or Copy report. Opening the panel does not reconnect or retry.

The report is a timeline of host-observed events — package preparation, launch, spawn, ready, each request dispatched, succeeded, failed, cancelled, rejected or timed out, late replies, and how the process ended — with sequence numbers, elapsed milliseconds, request ids and error codes.

It is deliberately safe to share: it contains no configuration values, launch arguments, executable paths, method names, request or response payloads, adapter error messages, stdout or stderr. It keeps the newest 256 events for up to 32 connections per run, and is cleared when the desktop restarts.

Remember where your output goes

Standard output is the protocol — anything you print there corrupts a frame and ends the connection. Standard error is discarded by the host. An adapter that needs logs must write them itself, to its own file or system log.

Reproduce outside the desktop

From the application repository:

npm run verify:adapter-sdk                      # export, build, pack, validate and host interop
cargo test -p shellcanvas-adapter-runtime --locked

These exercise the same protocol the desktop uses, without a device.

Resolution

What you see	Cause and fix
Adapter executable and working directory must be absolute paths	Launch configuration used a relative path.
Windows adapters must launch an explicit .exe, not a batch file or shortcut	Point the entrypoint at the executable itself.
Unable to start and supervise the trusted adapter executable	The process could not be spawned or supervised; check the file exists and is executable.
The adapter output ended or violated the protocol	Something wrote to stdout, or a frame was malformed. Remove stray printing.
The adapter sent an invalid response	An envelope did not parse, or carried unknown fields.
The adapter replied to an unknown request	A reply to an identity that was never sent or already finished.
Unsupported adapter protocol or invalid service catalog	initialize returned a catalog that breaks the naming, version or prefix rules.
This adapter does not advertise the requested method	The method is missing from your catalog — advertise it, or stop the caller from offering it.
Adapter has too many active requests	More than 32 in flight; reply busy rather than queueing without bound.
Adapter operation deadline expired before dispatch	The host gave up before sending. Look for a stalled adapter input pipe.
Adapter file does not match its manifest: <path>	An installed asset changed after review. Rebuild, then install again.
Adapter process cleanup could not be confirmed	A child process outlived the adapter. Make sure your process exits when its stdin closes.
Request exceeds the adapter frame limit; use a paged or streamed service	A single message went over 4 MiB. Page your results.

If a capability is missing rather than failing, the cause is almost always the catalog: compare what you advertised against the method lists in Adapter services. The host enables a role only when every required method is present, with an exact version match.

When to report an issue

Report when a failure survives these checks, and include:

• The diagnostics report from the panel — already redacted, and the most useful single artifact.
• Your platform and ShellCanvas version, and the adapter's id and version.
• Which services you advertise, and the exact method involved.
• A minimal reproduction, ideally with one of the SDK templates rather than your production device.

Keep device credentials, configuration values and captured payloads out of the report. If the problem is in your own adapter rather than the desktop, the same timeline usually shows it: a request dispatched with no reply points at your handler, while an invalid-response event points at your framing.

Related guides

• Adapter process protocol — the rules being enforced.
• Adapter services — advertising the right methods.
• Adapter packages — manifests, hashing and installation.
• Report a reproducible issue — the general reporting guidance.