Skip to main content
This reference documents errors that the baton-sdk and the connector runtime produce. Messages appear here as the SDK prints them, so you can search your logs for the exact text. Most SDK errors also carry a gRPC status code, shown in parentheses.

Configuration errors

connector does not have account manager configured

Code: Unimplemented Cause: C1 asked to create an account, but no resource type in the connector implements account creation. Solution: Implement CreateAccount and CreateAccountCapabilityDetails on a resource builder, or don’t request account creation from this connector. See CreateAccount. Two related messages:
  • connector has multiple account managers configured, but no resource type specified, and no default account manager configured: the request didn’t name a resource type, and the connector has several account managers but none on the user resource type. Register one on user, or have the request name a resource type.
  • connector does not have account manager configured for resource type: <type>: the request named a resource type that has no account manager.

resource type does not have credential manager configured

Code: Unimplemented Cause: C1 asked to rotate a credential on a resource type that doesn’t support it. Solution: Implement Rotate and RotateCapabilityDetails on that resource type’s builder, or don’t request rotation. A sibling message, resource type does not have credential issuer configured, means the same for credential issuance.

error: old account manager interface implemented for <type>

Cause: The builder’s CreateAccount method takes the older *v2.CredentialOptions. The SDK rejects it when the connector starts. The same error exists for credential managers (error: old credential manager interface implemented for <type>). Solution: Change the parameter to *v2.LocalCredentialOptions, and add CreateAccountCapabilityDetails:

error: duplicate resource type found for account manager <type>

Cause: Two resource syncers in your ResourceSyncers() result return the same ID from ResourceType(). The SDK registers each resource type once. The same check produces ...for credential manager <type> and ...for credential issuer <type>. Solution: Give each resource type a unique ID, and return each builder once.

Provisioning errors

resource type <type> does not have provisioner configured

Code: Unimplemented Cause: C1 sent a grant or revoke for a resource type whose builder doesn’t implement provisioning. Solution: Implement Grant and Revoke on the builder:
Also run the connector with --provisioning. See Implementing provisioning. Similar messages exist for resource creation and deletion: resource type <type> does not have resource Create() configured and resource type <type> does not have resource Delete() configured.

error: preferred credential creation option is not set

Code: InvalidArgument Cause: Your CreateAccountCapabilityDetails method returned details without a preferred credential option. This error comes from the connector’s own capability declaration, not from a request. Solution: Set PreferredCredentialOption, and include the same value in SupportedCredentialOptions:

error: preferred credential creation option is not part of the supported options

Code: InvalidArgument Cause: PreferredCredentialOption isn’t in SupportedCredentialOptions. Solution: Add the preferred option to the supported list, or choose a preferred option that’s already in it. The same two errors exist for rotation, with rotation in place of creation. Fix them in RotateCapabilityDetails.

Pagination errors

next page token unchanged

Code: Internal Messages:
  • listing resources failed: next page token unchanged (token=<token>, type=<type>, parent=<parent>) - likely a connector bug
  • listing entitlements failed: next page token unchanged - likely a connector bug
  • listing static entitlements failed: next page token unchanged - likely a connector bug
  • listing grants for resource <type>/<id> failed: next page token unchanged - likely a connector bug
Cause: Your List, Entitlements, or Grants method returned the same non-empty token it received. The SDK stops the sync instead of requesting the same page forever. It doesn’t detect longer loops, such as a token that alternates between two values. Solution:
See Troubleshooting.

page token corrupt

Cause: Bag.Unmarshal couldn’t parse the token it was given. This happens when you pass a token that didn’t come from Bag.Marshal or Bag.NextToken, or when a token was altered. Solution: Only unmarshal tokens that your own method returned.

C1z file errors

c1z: invalid file

Cause: The .c1z file is corrupted or isn’t a valid c1z. Solution:
  • Re-run the sync to generate a fresh file.
  • Check disk space and write permissions.
  • Verify that the file wasn’t truncated.

dotc1z: v1 (sqlite) c1z files are not supported

Cause: The file uses the older SQLite-based c1z format, which the current SDK can’t read. Solution: Convert the file with baton to-pebble, or delete it and run a fresh sync.

c1z: max decoded size exceeded

Cause: The decompressed c1z is larger than the decoder’s limit, which defaults to 10 GiB. Solution: Raise the limit with an environment variable. The value is in megabytes:

c1z: window size exceeded

Cause: Decompression needs more memory than the decoder allows, which defaults to 128 MiB. Solution: Raise the limit with an environment variable. The value is in megabytes:

pebble engine: output file path is empty

Cause: The sync had no output path. Solution: Set one with --file or -f. The default is sync.c1z, so this error is rare from the command line.

Action errors

action manager does not support encrypted action results

Code: Internal Cause: An action returned secret values, but the SDK’s action manager couldn’t encrypt them. Solution: Register actions that return secrets with actions.RegisterWithSecrets, and make sure the registry you register them on supports secret results.

action <name> not found

Code: NotFound Cause: C1 or a command requested an action that isn’t registered. Related messages are handler for action <name> not found and schema for action <name> not found. Solution: Check the action’s name against the schema you registered. To list a connector’s actions, run it with the hidden --list-action-schemas flag. To run one locally, use --invoke-action <name> --invoke-action-args '{...}'. See Custom actions.

action handler timed out

Cause: An action handler ran for longer than one hour. The SDK stops each handler after that, and the limit isn’t configurable. Solution: Make the action faster, or split the work into smaller actions.

Validation errors

error: validate provider not implemented

Code: InvalidArgument Cause: The connector doesn’t implement Validate. Every connector builder needs Validate, along with Metadata (error: metadata provider not implemented is the matching message). Solution:

validate failed

Message: validate failed: <error> Cause: The connector’s Validate method returned an error. The wrapped error contains the details. Solution: Read the inner error. It usually points to a credential or connectivity problem. The SDK retries Validate up to five times when it fails with an Unavailable or DeadlineExceeded status.

Input errors

input cannot be nil

Code: InvalidArgument Cause: You passed nil to connectorbuilder.NewConnector.

input is not a ConnectorServer, ConnectorBuilder, or ConnectorBuilderV2

Code: InvalidArgument Cause: You passed a value of the wrong type to connectorbuilder.NewConnector. Solution: Pass a value that implements ConnectorBuilderV2 (or ConnectorBuilder):
If you use config.RunConnector, the SDK calls this for you.

Encryption errors

age: failed to encrypt

Message: age: failed to encrypt: <error> Cause: Encrypting a credential failed. The wrapped error has the details. Solution: The most common cause is an invalid recipient public key. Related messages are age: failed to write encrypted data, age: failed to close, and age: failed to decrypt. The JWK ECDSA provider uses jwk-ecdsa: failed to encrypt and jwk-ecdsa: failed to decrypt. For decryption failures, verify that you’re using the private key that matches the public key used to encrypt.

Daemon mode errors

These messages appear when a connector runs with --client-id. See Troubleshooting for how to diagnose them.

HTTP status to gRPC code

The uhttp package turns HTTP error statuses into gRPC codes. The SDK retries a failed call only when the code is Unavailable or DeadlineExceeded.

Quick reference

Environment variables

Any flag also works as BATON_<FLAG_NAME>, in upper case with dashes as underscores. See Configuration schema reference.

Diagnostic commands