Skip to content
PLANOVI Docs

Operational Troubleshooting Runbook

This operational runbook provides step-by-step diagnostic checklists and remediation procedures for common issues encountered across the PLANOVI Webpage platform.

1. Cloudflare Turnstile Rejections (403 Forbidden)

Symptoms:

  • Contact form displays error: “Błąd weryfikacji antybotowej. Odśwież stronę i spróbuj ponownie.”
  • contact-handler.php returns HTTP 403.

Root Cause Analysis:

  1. Expired or unverified client widget challenge.
  2. Domain mismatch: The Turnstile site key is configured in Cloudflare Dashboard to only allow specific domains (e.g., planovi.app), rejecting localhost or test subdomains.
  3. Network timeout communicating with challenges.cloudflare.com.

Remediation:

  1. Verify domain whitelisting in Cloudflare Dashboard > Turnstile Sites.
  2. If testing locally, temporarily substitute the Cloudflare always-pass testing keys in config.php: 
    'turnstile' => [
        'site_key'   => '1x00000000000000000000AA',
        'secret_key' => '1x0000000000000000000000000000000AA',
    ]
  3. Test connectivity to Cloudflare API from the VPS:
    Terminal window
    curl -I https://challenges.cloudflare.com/turnstile/v0/siteverify

2. Supabase Form Message Insertion Failures (500 Server Error)

Symptoms:

  • Inbound contact submissions fail to appear in Supabase website_form_messages table.
  • Browser console shows 500 error from /contact-handler.php.

Remediation:

  1. Verify the Supabase Anon Key and Project URL in config.php: 
    'supabase' => [
        'url' => 'https://huaapueagfdjthltrzwq.supabase.co',
        'key' => '...',
    ]
  2. Test manual insertion via cURL:
    Terminal window
    curl -X POST 'https://huaapueagfdjthltrzwq.supabase.co/rest/v1/website_form_messages' \
      -H "apikey: SUPABASE_KEY" \
      -H "Authorization: Bearer SUPABASE_KEY" \
      -H "Content-Type: application/json" \
      -d '{"name":"Diagnostic Test","email":"diag@planovi.app","message":"Healthcheck"}'
  3. Inspect Supabase Dashboard Table Editor > website_form_messages for schema alterations or RLS policy restrictions.

3. Google Chat Webhook Alert Failures

Symptoms:

  • Form submissions succeed into Supabase, but the team’s Google Chat alert space receives no message.

Remediation:

  1. Check the webhook URL expiration or space configuration in config.php: 
    'google_chat' => [
        'webhook_url' => 'https://chat.googleapis.com/v1/spaces/...',
    ]
  2. Test dispatching a test card directly:
    Terminal window
    curl -X POST "https://chat.googleapis.com/v1/spaces/YOUR_SPACE/messages?key=...&token=..." \
      -H "Content-Type: application/json; charset=UTF-8" \
      -d '{"text": "Diagnostic ping from PLANOVI Webpage"}'
  3. If Google returns HTTP 400 or 403, regenerate the incoming webhook token in the Google Chat space settings.

Symptoms:

  • Opening documentation.php displays an empty iframe or 404 file not found.

Remediation:

  1. Verify that PDFs exist in the documents/ root directory:
    Terminal window
    ls -la documents/pl/
    ls -la documents/en/
  2. Ensure directory permissions allow web server read access:
    Terminal window
    chmod -R 755 documents/
  3. Check that the iframe path resolves to documents/{lang}/{filename} and not the legacy docs/ path.