Troubleshooting

Errors operators hit most often during install and steady-state operation, with the underlying cause and the fix for each. If your problem isn’t covered here, file an issue with the Zeotap account team and include the output of SHOW SERVICES IN APPLICATION <APP_NAME>; and the timestamp of the failure.

I see ZEOTAP where it should say ZEOTAP (or vice versa)

This was a build-time templating issue in earlier post-install renders, where some brand substitutions were missed and the literal ZEOTAP slipped into UI strings, error messages, or SQL identifiers in branded environments.

It’s fixed in the current Marketplace release. If you see it on a fresh install, you’re running a stale rendered SQL script — copy the Step 3 SQL block from the setup wizard inside your current install (it renders with brand identifiers already substituted) and re-run it. Existing identifiers (the proxy user name, the EAI names) keep their original spelling because dropping and recreating them would invalidate the cloud-side registration; the cosmetic mismatch is harmless.

sql: database is closed

This used to surface in the control-plane container during high-concurrency UI sessions when the in-app Postgres connection pool reused a connection that had been closed by the server side. The fix in the current release is to re-establish the connection on database is closed rather than fail the request, with a backoff for repeated failures.

If you see this on the current release, check SHOW SERVICES for the zeotap_postgres service status. A PENDING or FAILED Postgres service means the volume is unhealthy or the service has restarted and the control-plane pool is racing the restart. Wait sixty seconds and retry; if Postgres stays unhealthy, file a support ticket with the service-status output.

Future grant on objects of type SCHEMA to APPLICATION is restricted

This appears when you try to add GRANT ... ON FUTURE SCHEMAS TO APPLICATION <APP_NAME> (or the equivalent for tables, views, sequences) to your source GRANT script. Snowflake forbids future grants to applications because applications are transient identities that can be uninstalled, leaving orphaned future-grant rules.

The fix is to grant on existing objects only and re-run the GRANT block whenever you add new schemas or tables to the source database:

GRANT USAGE  ON ALL SCHEMAS IN DATABASE <DATABASE> TO APPLICATION <APP_NAME>;
GRANT SELECT ON ALL TABLES  IN DATABASE <DATABASE> TO APPLICATION <APP_NAME>;
GRANT SELECT ON ALL VIEWS   IN DATABASE <DATABASE> TO APPLICATION <APP_NAME>;

If you have frequent schema additions, wrap the GRANT block in a Snowflake task that runs hourly. The grants are idempotent, so re-running over already-granted objects is a no-op.

The registration request stays at requested or fails with ingress_url and auth_credential are required

The setup app’s Register with Zeotap button writes a row to APP_DATA.REGISTRATION_REQUEST. A goroutine inside the zeotap_control_plane SPCS service picks the row up, signs the body with the keypair from APP_DATA.CLOUD_CREDENTIALS, and POSTs to the cloud. If the row stays in requested for more than thirty seconds, or if the cloud returns ingress_url and auth_credential are required, one of three things is wrong:

• The proxy keypair hasn’t been generated yet. The operator skipped Step 3 or ran a partial version. Re-run the full Step 3 SQL block so GENERATE_PROXY_KEYPAIR runs and populates APP_DATA.CLOUD_CREDENTIALS (the proxy_user, proxy_role, and private_key_pem columns must all be non-empty), then click Register with Zeotap again.
• The SPCS public ingress isn’t ready. The application’s ingress endpoint is provisioned by SPCS asynchronously after the control-plane service is created. If you clicked Register with Zeotap immediately after install, the ingress URL might not have been resolvable yet. Wait until SHOW SERVICES IN APPLICATION <APP_NAME> reports zeotap_control_plane as READY, then click Re-register with cloud in the Step 4 card.
• The zeotap_sf_api_access EAI consent grant has not propagated. Confirm the reference shows Granted in Apps → <APP_NAME> → Configure. The SPCS control-plane service uses EXTERNAL_ACCESS_INTEGRATIONS = (REFERENCE('zeotap_sf_api_access')) for the outbound call; without the consent grant the call is blocked at SPCS egress.

Re-running the Step 3 SQL block and re-clicking Register are both safe. The request row’s error column records the last failure message — check it for the precise reason.

Source test or preview fails with No active warehouse selected (000606)

In the current release the application owns its warehouse (ZEOTAP_ADMIN_WH) and every SPCS service spec sets QUERY_WAREHOUSE = ZEOTAP_ADMIN_WH directly, so this error should not surface in a fresh install.

If you see it on an install that was upgraded from an older release (where the customer_warehouse reference path was still active), the long-running services may still be pinned to the old reference binding. Re-run PROVISION_SERVICES to repoint them at the application-owned warehouse:

CALL <APP_NAME>.APP_DATA.PROVISION_SERVICES();

The upgrade path of PROVISION_SERVICES calls ALTER SERVICE ... SET QUERY_WAREHOUSE = ZEOTAP_ADMIN_WH on every long-running service and re-applies the service spec to refresh in-container environment variables. After the proc returns, retry the source preview.

If the warehouse itself was not created, call PROVISION_SERVICES first — it creates ZEOTAP_ADMIN_WH (XSMALL, AUTO_SUSPEND = 60s) idempotently before issuing the ALTER SERVICE statements. Confirm with CALL <APP_NAME>.APP_DATA.GET_WAREHOUSE_INFO().

cannot list schemas: USAGE not granted

The control plane is trying to enumerate schemas in a source database it doesn’t have USAGE on. The most common causes:

• The GRANT block was never run for this source. Re-run the GRANT script the UI generated when you added the source.
• A new schema was created after the GRANT block ran. Snowflake’s ALL SCHEMAS grant only applies to schemas that existed when the GRANT was issued. Re-run the GRANT block to extend the grant to the new schema.
• The role that ran the GRANT block doesn’t own the database. Database-level grants require the database owner or ACCOUNTADMIN. Switch role and re-run.

After re-running the GRANT block, click Test connection on the source page in the Zeotap UI to confirm the application can reach the schemas again.

External access integration not enabled

A connector tried to call out to a destination’s host, but the EAI for that destination family isn’t bound to the application. Either the destination type was added before its EAI was provisioned, or the EAI was dropped after the fact.

The fastest fix is to re-grant the destination’s EAI reference from Apps → <APP_NAME> → Configure — Snowsight re-runs the consent flow and the application’s REGISTER_REFERENCE_CALLBACK re-attaches the EAI to the running SPCS services. Alternatively, re-run the destination’s fallback SQL block from the setup app’s destination grid — each block is idempotent and rebuilds the network rule + EAI without breaking anything. If the destination is outside the catalog, follow the BYO-EAI flow.

The dashboard shows “Connecting…” for a long time after install

The first UI call after install runs the embedded migration set in the in-account Postgres. The cloud proxy uses a 120-second timeout for this reason. If you see this for more than two minutes, check that all SPCS services are READY in Snowsight and that all required EAIs are bound. The control plane logs the migration progress; the Zeotap account team can pull the logs if needed.

Events accepted at the cloud (200 OK) but not in CDP_EVENTS.RAW_EVENTS

The forwarder’s warehouse-delivery lane batches events before flushing. Wait for the buffer to flush (size or time threshold) and re-check. Forwarding rules deliver in real time, but warehouse delivery is intentionally batched to keep INSERT cost low. If events still don’t land after five minutes, check zeotap_event_forwarder service status — a PENDING forwarder waits for the streaming buffer service on startup and won’t transition until it can connect.

Service stuck in PENDING

SHOW SERVICES lists a service as PENDING long after the others are READY. The most common cause is a missing inter-service dependency:

• The forwarder waits for the streaming-buffer service.
• The control plane waits for Postgres.
• Job services wait for the control plane.

Check the dependency in the service-graph order (Postgres → control plane → ingest/forwarder) and make sure each is READY before the next. If a service is stuck in PENDING with all dependencies READY, drop and recreate the service from Snowsight or contact support.

The claim URL says “App not found”

The cloud-side registration row hasn’t been created yet — the SPCS control-plane service either has not picked up the registration request from APP_DATA.REGISTRATION_REQUEST or has not yet completed the cloud handshake. Wait for SELECT * FROM <APP_NAME>.APP_DATA.CLOUD_REGISTRATION to return a row, then retry. If CLOUD_REGISTRATION is empty after you clicked Register with Zeotap in the Snowsight setup app (or called APP_DATA.REQUEST_REGISTRATION from SQL), see the registration-request entry above.