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 zeotap; 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_DISPLAY_NAME} 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 — request the latest rendered post-install bundle from your Zeotap account team and re-run the post-install step. 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 signalsmith_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 zeotap (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 zeotap;
GRANT SELECT ON ALL TABLES  IN DATABASE <DATABASE> TO APPLICATION zeotap;
GRANT SELECT ON ALL VIEWS   IN DATABASE <DATABASE> TO APPLICATION zeotap;

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.

register failed: 400 ingress_url and auth_credential are required

REGISTER_WITH_CLOUD POSTed an empty payload to the Zeotap cloud. The cloud needs both the SPCS public ingress URL and the encrypted keypair credential to bind the install. An empty body means one of two things:

• The proxy keypair hasn’t been generated yet. The operator skipped post-install-auth.sql or ran a partial version. Run the full post-install-auth.sql and the EXECUTE IMMEDIATE block calls GENERATE_PROXY_KEYPAIR before REGISTER_WITH_CLOUD, populating both fields.
• 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 ran post-install-auth.sql immediately after the application was created, the ingress URL might not have been written into APP_DATA yet. Wait until SHOW SERVICES IN APPLICATION zeotap reports signalsmith_control_plane as READY, then re-run post-install-auth.sql.

The fix is to run post-install-auth.sql end-to-end after the long-running services are READY. Re-running the script is rotation-safe.

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 post-install template’s section for that family was commented out, or the section was never run.

In Snowsight, open the application’s bindings and approve the relevant EAI from the catalog. Or re-run the relevant section of post-install-eais.sql — the script is idempotent, so re-running over an already-bound EAI rebuilds it 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 signalsmith_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 — register_with_cloud has not finished or has not run. Wait for SELECT * FROM zeotap.app_data.CLOUD_REGISTRATION to return a row, then retry. If CLOUD_REGISTRATION is empty after post-install-auth.sql finished, see the register failed entry above.