Troubleshooting

Start with the page that owns the failing workflow, then use server logs for the runtime view.

Useful Server Logs

sudo journalctl -u forge-cloud -f
cd /opt/forgecloud && sudo docker compose logs -f caddy buildkit

Deployment logs show Forge’s job-level view. Runtime logs show container output. Server logs show the underlying control plane, Caddy, and BuildKit behavior.

BuildKit Is Unavailable

Forge source builds need BuildKit at the configured BUILDKIT_HOST, usually tcp://127.0.0.1:1234.

Check:

• The deploy-buildkit service is running.
• The host port is not blocked locally.
• Docker is running.
• The BuildKit container is healthy.

App Starts but Does Not Respond

If a web deployment starts but fails the port probe:

• Confirm the service internal port matches the app’s listening port.
• Check runtime logs for a different port.
• Make sure the app binds 0.0.0.0, not only 127.0.0.1.
• Check that the service is not a worker or static site by mistake.

Static Output Fails

Static site deployments require an output directory containing index.html.

Check:

• The build command creates the expected folder.
• The Static output setting points at the correct path inside the image.
• The app is actually static. Server-rendered apps should run as web services.

DNS Is Pending

If a domain remains pending:

• Confirm the A record points to the server public IPv4.
• Confirm wildcard DNS for generated service hostnames.
• Wait for DNS propagation.
• Confirm Caddy is running and ports 80 and 443 are open.
• Click refresh and verify in the service Domains tab.

Email Send Fails With 554 Relay Access Denied

If a test send fails with:

SMTP server rejected the message with 554. (554 5.7.1 <recipient@example.com>: Relay access denied)

Forge reached the SMTP server, but Postfix did not trust the connection as local or authenticated.

For same-VPS Postfix:

• Confirm the identity uses the expected SMTP host and port, usually mail.example.com:587.
• Confirm Require STARTTLS is enabled for port 587.
• Confirm Postfix mynetworks includes loopback and the VPS host’s own public/private IPs.
• Confirm the MTA installer is current; it auto-detects non-Docker host IPs for mynetworks.
• If auto-detection is wrong, set FORGE_EMAIL_MTA_TRUSTED_NETWORKS.

Check on the VPS:

postconf -n mynetworks smtpd_relay_restrictions smtpd_recipient_restrictions
postconf -P submission/inet/smtpd_recipient_restrictions
sudo journalctl --since "10 minutes ago" --no-pager | grep -Ei "postfix|relay access|NOQUEUE"

OpenDKIM socket errors are separate but should be fixed too. OpenDKIM should run as opendkim:postfix so Postfix can write to the milter socket.

Railway Data Import Fails

Common causes:

• Railway returned only a .railway.internal database URL.
• Public networking is not enabled on the Railway database.
• The target Forge database is not deployed.
• TimescaleDB extension versions differ.
• The target PostgreSQL major version is older than the source.

Enable a public Railway database URL or use the direct URL import option.

Backups Fail

For database backups:

• Deploy the database service first.
• Confirm the engine supports backups.
• Confirm R2 is connected before choosing r2 or disk+r2.
• Check disk space for the local backup file.
• Check database credentials in service variables.

For disk+r2, a local backup can still succeed even when R2 upload fails. The backup record will show the R2 error.

Updates Fail

System Updates will not apply when the checkout is dirty, diverged, or cannot fast-forward.

For image installs, one-click update requires commit metadata and an image update command. Otherwise, run the shown Docker Compose command from the server.