Skip to main content
Version: 2026.04

Debugging Secure Connections

Beta Preview

Secure Connections is a beta preview feature in the April 2026 release. General availability (GA) is scheduled for the May 2026 release, available after May 29th, 2026.

This guide covers diagnosing and resolving common issues with Secure Connections, including configuration problems and sync failures.

Audience: Administrators with access to the Secure Connections admin panel. End users encountering issues should start with Secure Connections (User Guide) and contact their administrator if a problem persists.

Prerequisites​

Before troubleshooting an issue at the connection-configuration level, confirm that the underlying infrastructure is in place and healthy. Most "the connection won't work at all" symptoms trace back to deployment-level misconfiguration rather than anything done in the admin UI.

  • The Secure Connection Service (SCS) is deployed and reachable by the rest of the cluster. See Secure Connection Service Setup for the full deployment walkthrough, including the Helm chart, Zitadel role and machine user, S3 Inbox / Outbox buckets, Master Key, and required environment variables.
  • The SCS Master Key matches between SCS and the Registry Service (ISTARI_DIGITAL_SECURE_CONNECTION_SERVICE_MASTER_SECRET and FILE_SERVICE_REMOTE_MASTER_SECRET). See Master Key.
  • The Inbox / Outbox object stores referenced by the connection exist, are reachable, and the SCS and Registry Service have access (either via static keys or Pod Identities). See S3 Bucket Management.
  • The SCS Zitadel machine user has the rss_service_user role granted on the Istari project. See Zitadel.

Debugging Secure Connection Sync​

To view the most recent sync attempts, click the colored (red/yellow/green) sync status icon on the far left of the row in the Sending Connections or Receiving Connections table.

Sending Side Checks​

Sync Failures​

Error messageResolution
shared secret unavailable: InvalidTokenThe Master Secret has rotated. Reset the shared secret on the connection, and if its value changed, re-share it with the receiving Istari instance.
connection failed (no manifest produced): bucket not configured: No RSS object-store configuration for labelThe S3 bucket configuration is not duplicated correctly between the Registry Service and SCS. See S3 Bucket Management.
outbox write failed: Revision <uuid> size=<n> exceeds single-op copy_object ceilingThe file is larger than the ~2 GB per-file cap and cannot be transferred through a Secure Connection. The file is excluded from sync; other shared files on the connection continue to flow. Support for files larger than 2 GB is planned for a future version.

Sync Succeeds, File Not Received​

  1. Click With Updates to filter the sync history to events that contain newly pushed files. Confirm the resource ID of the affected file appears in a successful sync. If it does, the file has left the sending side cleanly — skip to Receiving Side Checks.
  2. If the Outbox was changed after the Sending Connection was created, the file may need to be re-published. Unshare the file, wait for the next sync, and re-share it.
  3. Confirm the Outbox is configured to the correct S3 bucket. See S3 Bucket Management.

Receiving Side Checks​

Sync Failures​

Error messageResolution
properties read failed: An error occurred (NoSuchKey) when calling the GetObject operation: The specified key does not exist.This can appear if bucket configuration was changed after files were pushed. Ask the sending side to create a new connection to resolve.
connection failed (no manifest received)Confirm the Shared ID matches the Shared ID on the sending side exactly. Confirm the Inbox is receiving files as expected (i.e. manifest files located in <SHARED_ID>/shard0/manifest). See S3 Bucket Management.
connection failed (no manifest produced): bucket not configured: No RSS object-store configuration for labelThe S3 bucket configuration is not duplicated correctly between the Registry Service and SCS. See S3 Bucket Management.
manifest control tag(s) uncovered by any transformation predicate: ...Set up a transformation configuration for the incoming control tags on the receiving connection. See Transform Config.
manifest max infosec level '<level>' (order=<n>) exceeds local platform maxThe sending Istari instance is at an infosec level higher than this receiving instance allows.

Sync Succeeds, File Not Received​

  1. Confirm the user trying to view the file is an owner of the receiving connection. See Manage Owners (Receiving Connections).
  2. Confirm the user holds the infosec level and control tags required for the file.
  3. If the file is an unparented artifact, follow the steps in Finding Artifacts Shared to You Individually.

Other Issues​

Sync Has Not Run Recently​

If a connection has not produced a sync event in some time and no error appears in the table above, ask your IT administrator to verify the Secure Connection Service deployment and review the SCS container logs for signs of misconfiguration.

Receiving Connection Issues​

Incoming Artifacts Are Not Visible​

If an artifact arrived through a receiving connection but a user cannot find it, see Finding Artifacts Shared to You Individually in the user guide.