Skip to main content

Connection errors

When a connection fails, the error message tells you the layer that broke. Match the error pattern below to the cause.

Authentication failures​

401 Unauthorized / 403 Forbidden​

The credentials Honeyframe is sending are wrong, expired, or insufficient.

  • Wrong credentials — re-enter the password / API key in the connection settings. Many secret stores trim trailing whitespace; if you copy-pasted, check for a stray space.
  • Expired token — OAuth-based connections (Google Sheets, Salesforce) refresh tokens automatically, but the refresh chain breaks if the user who authorized the connection rotates their own credentials. Re-authorize the connection.
  • Insufficient scopes — the connection was authorized with a narrower scope than the operation requires. Look at the request that failed: if it's hitting a write endpoint and your OAuth token only has read scopes, re-authorize and pick the right scopes.

Invalid grant (OAuth specifically)​

The OAuth refresh token was revoked. Re-authorize from scratch — Honeyframe will generate a fresh consent flow.

Network failures​

Connection refused / Could not connect to host​

Honeyframe can't reach the source at all.

# From the Honeyframe server, check basic reachability:
ssh root@<honeyframe-host> "nc -zv <source-host> <port>"

# If on-prem source:
ssh root@<honeyframe-host> "ping -c 3 <source-host>"

Most common causes, in order:

  1. Firewall / security group — the source's network blocks the Honeyframe server's IP. Add Honeyframe's egress IP to the allowlist. Find Honeyframe's egress IP under Admin → Network → Outbound IPs.
  2. VPN / private network — the source is in a VPC the Honeyframe server isn't peered with. Either move Honeyframe to the same VPC or set up a bastion / reverse tunnel.
  3. Source is down — sometimes the simplest answer. Hit the source directly (not through Honeyframe) to confirm.

SSL: CERTIFICATE_VERIFY_FAILED​

The source's TLS cert isn't trusted by Honeyframe. Either:

  • The cert is self-signed and you need to upload its CA bundle in Connection settings → Advanced → Custom CA bundle
  • The cert expired (check with openssl s_client -connect host:443 </dev/null 2>/dev/null | openssl x509 -noout -dates)
  • The host's nginx/lb is misconfigured and serving the wrong cert chain

For dev environments only, you can disable verification (Skip SSL verification toggle) — but never in production. It silently masks a real misconfiguration that will eventually bite.

Schema drift​

Column "X" does not exist / Schema mismatch​

The source's schema changed since Honeyframe last introspected it. New column added, column renamed, type changed.

  1. Open the connection → Refresh schema. Honeyframe re-introspects and updates its cached schema.
  2. Audit downstream — recipes/dashboards that referenced the dropped/renamed column will now show validation errors. Fix them before re-running flows.
  3. Consider locking the source's schema with a contract — production data sources should not be subject to silent schema drift; coordinate with the upstream owner.

Throttling​

429 Too Many Requests / 503 Service Unavailable​

The source is throttling Honeyframe.

  • Reduce the connection's Max concurrent queries under connection settings. Default is 4; drop to 1 for sources with strict per-user rate limits (some BI APIs cap at 60 req/min).
  • For flow runs, lower the flow's Max parallel workers (see Reduce flow runtime) — every parallel step is another request.
  • For repeated full scans, switch to Incremental mode so each run pulls only the delta.

If throttling is persistent and unfixable on the Honeyframe side, contact the source vendor about a higher rate limit. Some offer a service tier specifically for analytics workloads.

Diagnostic checklist​

When you don't know the cause yet:

# 1. Test the connection in isolation
# Connection → Test → Run probe

# 2. Look at the actual request/response Honeyframe sent
# Connection → Activity → Last failure → "View request"

# 3. Reproduce the request from outside Honeyframe
# Use the request body shown above, fire it from your laptop with curl/psql/whatever the source speaks.
# If your laptop fails the same way → it's not a Honeyframe-network problem.
# If your laptop succeeds → it's network or auth scope between Honeyframe and the source.

See also​

  • Permissions Reference — for 403s that are about Honeyframe's own permission system, not the source's
  • Audit Logging — connection attempts (success and failure) are logged with the user who triggered them