Connection and troubleshooting
Diagnose endpoint setup, reads and writes without conflating their checks
What this page helps you verify
A data endpoint binds a workspace name to a concrete target through an installed capability. These checks help locate whether a failure comes from installation, target configuration, permissions or execution.
Plugin used
Troubleshoot the plugin actually bound to the endpoint. Its contract and implementation determine which checks, discovery, reads and writes exist. Installation details are in Plugins; complete endpoint-specific examples are in Setup guides.
What you need
Have the endpoint's workspace, installed capability/version, redacted target and failing operation available. Use a small known record or dedicated write fixture to compare expected and actual behavior.
Capability missing from the picker
Confirm you selected the correct workspace and installed a capability matching the desired role. A package can bundle read, write and store capabilities; select the actual installed one. A transform, skill, secret provider or MCP tool is not a generic endpoint connector.
For a custom package, inspect publication, installed version, capability declaration and contracts. Follow custom plugin troubleshooting before inventing target fields.
Target rejected
Compare the endpoint's contract kind and selectors with the installed capability's contract. Required fields, enums and field types must match. Iceberg namespace is an array; News/Web's source URL belongs to installation configuration; HTTP Dataset requires request and response settings.
Connection check fails
Check credentials, runtime network reachability, TLS, allowlists and external grants. A browser reaching the service does not prove the execution runtime can. Rotate credentials on the installation and repeat the supported check.
Schema missing or unexpected
Discovery depends on connector support and source permissions. Configure a known target manually where supported, then verify an actual bounded read. Review multiple document shapes, nulls and upstream type changes. Schema hints are metadata, not external constraints.
No records or wrong records
Check target, account/database, filters, API array path, time window and pagination. Compare a known key with the source. Empty results can be valid; a successful check does not prove records exist. Inspect API error envelopes and run telemetry.
Save succeeds but no data appears
Endpoint creation is configuration. Execute a supported read or a pipeline run to process records. A freshness value does not schedule anything. Inspect the pipeline's saved version, run and checkpoints before enabling recurrence.
Write or historical operation unavailable
Read and write capabilities differ. Generic destination support does not grant Iceberg source-write recovery, snapshots or maintenance. Check write access and operations, applicable policy and caller grants.
Endpoint visible from another project
Endpoints are workspace resources. Projects in that workspace can reference the same endpoint subject to permissions. To use a separate external target, create another endpoint; do not duplicate resources merely because the project differs.
Before reporting a problem
Include workspace/endpoint identifiers, installed package version, contract kind, redacted target, failing operation and run/error details. Exclude tokens, passwords and private records. See getting help.
A source is stale or disconnected
Check the endpoint connection, credentials, target, and schema. Inspect the last successful pipeline read and connector telemetry/checkpoint. Installation alone does not sync data. Check the pipeline schedule and its operating status.