Astro Bridge Troubleshooting

Issues connecting UniSync to an Astro site via the Bridge API.

For initial setup instructions, see the Astro CMS guide.

---

Bridge API Not Reachable

Symptoms: UniSync shows "Connection refused" or "Cannot connect to Astro Bridge" when testing the environment or publishing content. Timeout errors after several seconds.

Cause: The Bridge API process is not running, the URL or port is wrong, or a firewall is blocking the connection.

Resolution:

1. Verify the Bridge API is running on the target server:

   # Check if the process is running
   ps aux | grep bridge
   
   # Check if the port is listening
   curl http://localhost:YOUR_PORT/health

2. Check the URL in UniSync: Go to the publish environment settings and verify:
   • The URL includes the correct protocol (http:// or https://).
   • The port number matches what the Bridge API is listening on.
   • There is no trailing slash.
   • If the Bridge is on a remote server, use the server's public IP or domain, not localhost.
3. Check firewall rules: Ensure the port is open:

   # Linux (ufw)
   sudo ufw status
   
   # Check if port is accessible from outside
   curl http://YOUR_SERVER_IP:YOUR_PORT/health

4. Check the Bridge API logs for startup errors. Common issues:
   • Port already in use by another process.
   • Missing configuration file.
   • Permission denied on the listening port (ports below 1024 require root).

---

Authentication Failures

Symptoms: Bridge API responds but returns 401 Unauthorized or 403 Forbidden. The connection test fails with an authentication error.

Cause: The API key configured in UniSync does not match the key the Bridge API expects.

Resolution:

1. Check the API key in UniSync's publish environment settings.
2. Compare it with the key configured in the Bridge API's environment or config file.
3. Keys must match exactly -- watch for:
   • Leading or trailing whitespace (copy-paste issues).
   • Different keys for different environments (staging vs production).
4. If you have lost the key, generate a new one in the Bridge API configuration and update it in UniSync.
5. Test authentication directly:

   curl -H "Authorization: Bearer YOUR_API_KEY" \
     http://YOUR_BRIDGE_URL/health

---

File Write Permissions

Symptoms: Bridge API returns 500 Internal Server Error or a message about permission denied. The API is reachable and authentication succeeds.

Cause: The Bridge API process does not have write permissions to the Astro project's content directory.

Resolution:

1. Check the content directory path in the Bridge API configuration. It should point to the src/content/ directory (or equivalent) in your Astro project.
2. Verify permissions:

   ls -la /path/to/astro-project/src/content/

   The user running the Bridge API process must have write access.
3. Fix permissions:

   # Make the Bridge API user the owner
   chown -R bridgeuser:bridgeuser /path/to/astro-project/src/content/
   
   # Or grant group write access
   chmod -R g+w /path/to/astro-project/src/content/

4. Check SELinux or AppArmor: On systems with mandatory access controls, you may need to add an exception for the content directory.
5. Check Bridge API logs for the exact file path that failed -- it may reveal a misconfigured content directory path.

---

Build Trigger Failures

Symptoms: Content is written to the Astro project successfully, but the site does not rebuild. New posts are not visible on the live site.

Cause: The build trigger (webhook, CI/CD pipeline, or local build command) is not configured or is failing.

Resolution:

1. Check if builds are configured: The Bridge API can optionally trigger a build after writing content. Verify this is enabled in the Bridge configuration.
2. Check build command: If the Bridge runs a local build:

   # Test the build manually
   cd /path/to/astro-project
   npm run build

   Fix any build errors before expecting automated builds to work.
3. Webhook-based builds (Netlify, Vercel, etc.):
   • Verify the webhook URL is correct in the Bridge configuration.
   • Check the hosting provider's deploy logs for errors.
   • Test the webhook:

     curl -X POST https://api.netlify.com/build_hooks/YOUR_HOOK_ID

4. CI/CD pipeline: Check the pipeline logs (GitHub Actions, GitLab CI, etc.) for build failures.
5. Rate limits: Some hosting providers limit the number of builds per hour. If you are publishing many posts rapidly, builds may be queued or dropped.

---

Content Not Appearing After Publish

Symptoms: The Bridge API reports success, the build completes, but the new content is not visible on the live site.

Cause: Build cache, CDN cache, or content schema mismatch.

Resolution:

1. Clear the build cache:

   cd /path/to/astro-project
   rm -rf .astro/  # Astro build cache
   rm -rf dist/    # Previous build output
   npm run build

2. Clear CDN cache: If you use Cloudflare, Netlify, or another CDN:
   • Purge the cache from the CDN dashboard.
   • Or wait for the TTL to expire (can be minutes to hours depending on config).
3. Check content schema: Astro content collections validate frontmatter against a schema. If the published content has missing or incorrect fields, Astro silently excludes it.
   • Check src/content/config.ts for the expected schema.
   • Verify the Bridge API is generating frontmatter that matches.
   • Run npm run build locally and look for content collection warnings.
4. Check the file was written correctly:

   # List recently modified files
   ls -lt /path/to/astro-project/src/content/blog/ | head -5
   
   # Inspect the frontmatter
   head -20 /path/to/astro-project/src/content/blog/your-new-post.md

5. Draft status: If the content has draft: true in its frontmatter, Astro excludes it from production builds by default. Check the Bridge API's default frontmatter settings.

---

Diagnostic Checklist

• [ ] Bridge API process is running
• [ ] Bridge URL and port are correct in UniSync environment settings
• [ ] API key matches between UniSync and Bridge configuration
• [ ] Firewall allows traffic on the Bridge port
• [ ] Bridge API health endpoint responds: curl http://BRIDGE_URL/health
• [ ] Content directory exists and is writable by the Bridge process
• [ ] Build trigger is configured and working
• [ ] Content schema matches Astro collection config
• [ ] CDN/build cache has been cleared after troubleshooting