Skip to content

Troubleshooting Playbook

When an extension or automation misbehaves, start here. This playbook consolidates the most common production issues and points you to the right diagnostic tools.

1. Authentication & CLI issues

Symptom Checks Reference
401 Unauthorized when calling the REST API Ensure you’re using a workspace API token (Settings → API Tokens). Legacy extension API keys only work under /api/v1/ext. REST API → Authentication
CLI commands prompt for login each run Run kiket auth login once per environment. Tokens live under ~/.config/kiket/credentials.json; delete the file to reset. kiket --help
MCP server shows "Forbidden" Invite the MCP integration user to the workspace or issue a new workspace token. API Authentication

2. Extension delivery failures

  1. Check the delivery log – Settings → Extensions → Recent Deliveries (or kiket extensions deliveries list). Look for the failure_reason and diagnostics payload.
  2. Inspect secrets – The new secret health panel highlights expiring or failing keys. Rotate secrets via CLI or Settings and confirm next_rotation_at.
  3. Replay – Use the webhook guardian reference extension or kiket extensions deliveries replay <id> to rerun with the same payload.
Error Root causes Fix
delivery.timeout Endpoint exceeded manifest’s timeout_seconds. Raise the timeout or ensure upstream responds within 10s.
delivery.validation Invalid response schema. Compare payload with responses.success schema in manifest.
secret.unavailable Secret missing or secret-store error. Check Settings → Extension Secrets and GSM permissions.

3. dbt & Analytics

Cloud Build dbt runs now emit analytics.dbt.* events and log artifacts to the configured GCS bucket. To debug:

  1. Visit Cloud Build history (kiket-analytics-dbt-trigger) to read stdout/stderr.
  2. Pull artifacts from gs://<project>-analytics-dbt/runs/<build-id>/logs/dbt.log.
  3. Use the analytics/dbt_runner_spec.rb tests as a reference for environment variables (DBT user, schema grants).

Common errors:

  • invalid value for 'build.substitutions' → custom build substitutions must start with _. Update Cloud Build trigger definitions.
  • missing libyaml / libffi → ensure the build step installs libyaml-dev and libffi-dev if using custom images.

4. Config-as-Code failures

Symptom Resolution
Loader skips definitions silently Review logs/configuration_loader.log and ensure workspace repo follows the Config-as-Code structure.
YAML validation errors Run bundle exec rake configuration:validate REPO=path locally before pushing.
Command palette actions missing Confirm the workflow repository exports the action manifest. See Command Palette.

5. Support escalation

  • Diagnostics bundle – Include Cloud Build log links, delivery IDs, and relevant issue IDs.
  • Contact – support@kiket.dev or in-app “Share Feedback” (Cmd/Ctrl + K → “Feedback”).
  • SLA – Paid plans receive 1-business-day response; urgent incidents page engineering via PagerDuty.

Keep this page nearby; each section links back to the detailed documentation so you can jump from symptoms to fixes quickly.