Troubleshooting

This guide covers common issues and their solutions. If you don't find your answer here, check the deployment logs for specific error messages.

Deployment Issues

Deployment fails immediately

Symptoms: Deployment status shows "Failed" right after starting.

Solutions:

Check GitHub connection
- Go to Deploy Forge → Settings in WordPress admin
- Verify connection shows "Connected"
- If not, click "Connect" to re-authorize
Verify repository access
- The GitHub App must have access to your repository
- Go to GitHub → Settings → Applications → Deploy Forge → Configure
- Ensure your repository is selected
Check workflow file (GitHub Actions method)
- Verify workflow file exists in .github/workflows/
- Ensure workflow has workflow_dispatch trigger for on-demand deployments
- See Workflows for requirements

Build succeeds but deployment fails

Symptoms: GitHub Actions shows success, but Deploy Forge shows failed.

Solutions:

Check artifact upload
- Your workflow must upload an artifact using actions/upload-artifact
- Verify the upload step exists and succeeds in the workflow run
- When multiple artifacts exist, Deploy Forge selects the largest one
Check file permissions
- WordPress must have write access to wp-content/themes/
- Verify directory permissions: 755 for folders, 644 for files
Check disk space
- Insufficient space prevents file extraction
- Clear old files or increase disk allocation

No artifact available

Symptoms: Workflow completes but no artifact is available for download.

Solutions:

Your workflow may not have an actions/upload-artifact step
The artifact may have expired (GitHub retains artifacts for 90 days by default)
The upload step may have failed — check the workflow run logs on GitHub

Fix by adding to your workflow:

- uses: actions/upload-artifact@v4
  with:
    name: theme-build
    path: dist/

Deployment stuck in progress

Symptoms: Deployment status hasn't updated for a long time.

Solutions:

Check GitHub Actions
- Go to your repository → Actions tab
- Find the workflow run and check its status
- If queued, GitHub may be experiencing delays
Check webhook delivery
- Deploy Forge relies on GitHub webhooks to track workflow progress
- Go to GitHub → Settings → Developer settings → GitHub Apps → Deploy Forge → Advanced
- Check recent webhook deliveries for errors
Trigger a new deployment
- If a deployment is stuck, trigger a new one manually from WordPress

Automatic Deployment Issues

Push not triggering deployment

Symptoms: You push code but no deployment starts.

Solutions:

Verify branch matches
- Deployments only trigger for your configured branch
- Pushing to develop won't trigger if branch is set to main
- Check your branch setting in the Deploy Forge dashboard
Check site connection
- Go to Deploy Forge in WordPress admin
- Verify your site shows as Connected
- If not connected, click Connect to re-establish (you'll be redirected to the Deploy Forge app to complete setup)
Check deployment history
- Go to Deploy Forge → History
- A deployment may have been created but failed for another reason

Webhook signature errors

Symptoms: Deployment logs show signature validation failed.

Solution: There are two possible causes:

GitHub-to-Deploy Forge signature mismatch — This is a server-side configuration issue. If you see this consistently, contact support.
Deploy Forge-to-WordPress signature mismatch — Your site's webhook secret may be out of sync. To fix:
1. In WordPress admin, go to Deploy Forge
2. Click Disconnect
3. Click Connect to re-establish the connection
4. Try pushing again

Connection Issues

GitHub connection errors

Symptoms: Connection test fails or GitHub operations error.

Solutions:

Re-authorize
- In WordPress admin, go to Deploy Forge
- Click Disconnect then Connect
- Complete the setup in the Deploy Forge app
Check GitHub status
- Visit githubstatus.com
- If GitHub is down, wait and retry
Check firewall/hosting
- Your server must allow outbound HTTPS to api.github.com
- Some hosting providers block external API calls

Rate limit errors

Symptoms: API errors mentioning rate limits.

Solutions:

Wait for reset
- GitHub API rate limits reset hourly
- Deploy Forge also has its own rate limiting to prevent abuse
Reduce deployment frequency
- Batch commits instead of pushing frequently
- Use manual deployments during heavy development

WordPress Issues

Theme not appearing after deployment

Symptoms: Deployment succeeds but theme unchanged.

Solutions:

Clear cache
- Clear your caching plugin (WP Super Cache, W3 Total Cache, etc.)
- Clear server-level cache if applicable
- Clear CDN cache (Cloudflare, etc.)
Verify target directory
- Check that the deployed files match your active theme's folder name
- The directory structure in your artifact/repository must match what WordPress expects
Check file extraction
- Theme files should be at the correct level, not nested in extra folders

Permission denied errors

Symptoms: Logs show "Permission denied" or "Unable to write".

Solutions:

Fix directory permissions

chmod 755 wp-content/themes/
chmod 755 wp-content/themes/your-theme/

Fix file ownership
```
chown -R www-data:www-data wp-content/themes/your-theme/
```
(Replace www-data with your web server's user)
Contact hosting support
- Some managed hosts restrict file operations
- Ask them to grant write access to themes directory

Getting More Help

Enable Debug Logging

In the WordPress plugin settings, enable Debug Logging to capture detailed information about deployment steps, API calls, and errors. Check Deploy Forge → Logs in WordPress admin for the output.

Check WordPress Debug Log

Add to wp-config.php:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

Check wp-content/debug.log for errors.

Collect Information for Support

When contacting support, include:

WordPress version
PHP version
Deploy Forge plugin version
Deployment method (GitHub Actions or Direct Clone)
Error messages from logs