Configuration and troubleshooting

Start with the operation that failed: installation, connection check, endpoint validation, pipeline preflight or execution. These stages verify different things.

Credentials and configuration

Keep credentials in protected installation settings or a supported secret-provider path. Inspect required fields and nested schemas for the installed version. A URL or target selector is not a credential; a schema’s secret flag is not a universal redaction guarantee.

If a runtime cannot resolve a secret reference, check that the provider is registered there and the name is permitted. Environment Variables require explicit operator configuration.

Plugin missing from Explore

Confirm the workspace, catalog filters, plugin status and deployment’s published artifacts. Source packages existing in the repository do not prove their artifacts are available in the current hosted catalog. Use catalog discovery to inspect the caller-visible entries.

Connection check fails

Check network reachability from the execution runtime, TLS, credentials and service permissions. Read the actual returned error. A passing probe is not a test of every target or write path.

Endpoint validation fails

Select a capability whose contract matches the target. Validate table, collection, path, graph or request settings separately from the connection. A plugin installation can carry several capabilities; the selected capability installation must support the desired operation.

Pipeline preflight fails

Inspect missing installations, capability status, runtime support, parameters, bindings and input/output shape. Ensure the node references the installed executable capability rather than a catalog entry alone. Do not replace an AI capability with a different deterministic operation to silence validation.

Execution fails after validation

Inspect the durable run and plugin error, provider response, data bounds, checkpoint state and resource permissions. For an uncertain write, inspect the receipt and supported recovery path before issuing another write.

Iceberg writes and governed action reconciliation have specific adapter and policy requirements. A generic connector retry is not a guarantee against duplicate external effects.

Custom package fails validation

Check craven.plugin.yaml, declared resource paths, package exports, runtime implementation and actual command output. Missing build output, invalid skill frontmatter, mismatched contracts and unsupported capability kinds require package repair before publication.

See Test and publish for the status and review flow.

Ask for help

Include the stage, plugin name/version, capability kind, sanitized target, run or operation ID, returned error and what you expected. Keep passwords, tokens, connection strings containing credentials and private source records out of shared reports.