# Troubleshoot Stampwing setup and sending

Practical fixes for installation errors, missing keys, wrong environments, validation failures, limits, queued mail, DNS, and uncertain outcomes.

Author: Stampwing
Canonical: https://www.stampwing.com/guides/stampwing-troubleshooting
Published: 2026-10-05
Reviewed: 2026-10-05
Category: Engineering

Turn a setup error or missing message into a specific next action and a useful support report.

## Short answer

Section link: https://www.stampwing.com/guides/stampwing-troubleshooting#short-answer

Find the last confirmed step: app startup, credential check, queue acceptance, provider submission, or receiving-server acceptance. Diagnose the existing operation before retrying. Keep its message UUID and idempotency key so recovery does not create a duplicate.

## Before you start

Section link: https://www.stampwing.com/guides/stampwing-troubleshooting#before-you-start

For: Developers installing Stampwing or supporting an integration.

Bring: The failing step, HTTP status and code if present, UTC timestamp, environment, project, request ID, and any message UUID.

Scope: Diagnostics are read-only unless you explicitly choose a repair. Never share API keys, encryption secrets, authentication tokens, message bodies, or password-reset links in a public report.

## Start with a read-only credential check

Section link: https://www.stampwing.com/guides/stampwing-troubleshooting#first-check

Call GET /api/v1/doctor, or client.doctor() in the SDK. The response identifies the credential’s project, environment, and permissions and says sent: false. It works with a send-only key, but that does not grant permission to read messages.

For an existing message, use Messages or client.diagnoseEmail(id) with email:read. Preserve the UUID from the original acceptance response. Diagnosis explains stored evidence and does not resend.

Shell variables must already be set; cURL does not read .env files

```shell
curl --fail-with-body --max-time 15 \
  "$POSTRUNE_BASE_URL/api/v1/doctor" \
  -H "Authorization: Bearer $POSTRUNE_API_KEY"
```

## Installation and connection problems

Section link: https://www.stampwing.com/guides/stampwing-troubleshooting#install-errors

| Symptom | Likely check | Next step |
| --- | --- | --- |
| Environment file not found / missing variable | Working directory, exact .env.stampwing filename, and --env-file option. | Keep the environment file beside the script and run there. Remove accidental .txt suffixes. Do not print the file contents into logs. |
| Cannot find @postrune/sdk or registry 404 | The SDK has not been published through this guide’s installation path. | Build a local tarball from packages/sdk and install that archive in your consumer app. |
| Cannot find package.json | The terminal is in the wrong folder. | Open the repository root for app commands or the consumer app for SDK installation. |
| Connection refused / ECONNREFUSED | Wrong origin, port, or stopped process. | Use 3017 for the web app, 5434 for the provided database; start the relevant process. |
| Docker command exists but cannot connect to the daemon | Docker Desktop or the Docker daemon is stopped. | Start it and wait for docker info to succeed before Compose. Or choose the dedicated local PostgreSQL option. |
| Migration says permission denied to create role, or worker reports row-level security | The ordinary database owner does not meet the local demo role requirements. | Use the provided Compose service or the dedicated local-demo role in the install guide. Do not disable RLS or modify a shared production role. |
| Database login or migration error | Wrong DATABASE_URL or database not healthy. | Confirm the dedicated database and role. Run migrations against that database before starting. |
| Port already in use | An existing process owns the port. | Use that intended instance or stop it deliberately. If changing the web port, update APP_ORIGIN, client URL, and startup command together. |
| /app redirects to waitlist / SETUP_IN_PROGRESS | You reached a public-only deployment. | Use the local fixture or an accessible installation. Do not infer that accounts or sending are enabled. |
| Encryption/decryption error | The original key is missing or changed. | Restore the correct secret from your secret store; preserve the database and do not regenerate keys over stored data. |

## HTTP errors and the right recovery

Section link: https://www.stampwing.com/guides/stampwing-troubleshooting#api-errors

| Response | What to check | Recovery |
| --- | --- | --- |
| 400 validation / issues | Field names, types, unknown fields, and idempotency format. | Use the first field-specific issue. Do not add mode to a send body. |
| 401 UNAUTHORIZED | Missing, invalid, expired, or revoked Bearer key. | Load the intended server secret; create a replacement if lost and revoke the old key. |
| 403 permission or live-access error | Required capability, environment, suspension, and stored readiness. | Use the least-privileged correct key; resolve the stated account condition. Normal signup access is automatic. |
| 404 NOT_FOUND | Origin, endpoint path, UUID, project/environment, retention. | Use the same project and environment as the original send. Inaccessible and missing IDs intentionally look alike. |
| 409 IDEMPOTENCY_CONFLICT | Same key with changed content, mode, or conflicting header/body key. | Recover the original frozen payload. Only use a new key for a genuinely new authorized event. |
| 409 PROJECT_PAUSED | Persisted project pause. | Read the reason and resume only when the underlying issue is resolved. |
| 413 / 415 | Request size, attachment encoding, or Content-Type. | Reduce content or use documented attachment references; send uncompressed UTF-8 application/json. |
| 422 UNKNOWN_EVENT | Workflow event name and declared schema. | Publish a workflow that declares the event before ingesting it; do not invent event namespaces. |
| 429 RATE_LIMITED | API request rate and Retry-After. | Back off within a bounded budget using the same key and body. |
| Quota / spending-limit rejection | Workspace usage, plan, UTC daily allowance, optional project caps. | Wait for the stated reset or adjust an authorized plan/cap. A new key does not reset usage. |
| 503 CONFIGURATION / TENANT_REQUIRED / RECOVERY_PAUSED | Deployment configuration, provisioning, recovery state. | Ask the operator to resolve the named prerequisite; preserve the existing operation identity. |

Note: Read the code and message as well as the HTTP status. Not every 429 is a transient rate limit, and a proxy’s 503 may not come from Stampwing.

## A successful response, but no email arrived

Section link: https://www.stampwing.com/guides/stampwing-troubleshooting#no-email

1. Read mode first. demo means simulated delivery; a Test message never arrives in a real inbox.
2. For queued mail, check the worker, project/workspace pauses, screening, and allowance evidence. Do not queue a second copy while the first waits.
3. For submitted mail, inspect provider feedback. Missing feedback is not proof of failure.
4. For accepted mail, check spam, quarantine, mailbox rules, forwarding, and recipient-side message tracing. The receiving server accepted it, but inbox placement is unconfirmed.
5. For uncertain mail, use the original UUID and operator evidence to reconcile. Do not automatically resend.

[Follow the full missing-email investigation](https://www.stampwing.com/guides/email-delivered-but-not-received)

## Separate a failed send from a failed status lookup

Section link: https://www.stampwing.com/guides/stampwing-troubleshooting#timeout-recovery

A non-JSON proxy error is still useful evidence: keep the HTTP status, X-Request-Id if present, and retry timing. The example does not echo raw response bodies, which might contain credentials or application data. It never automatically retries.

| Last confirmed evidence | Next action |
| --- | --- |
| doctor failed; no POST started | Fix the origin or credential. No message was submitted by the guarded sender. |
| POST started; no valid response | Inspect Messages. If a retry is appropriate, use the same saved body and operation key. |
| A message UUID was printed; GET failed | Keep the UUID. Run the guarded sender with --status UUID or call getEmail(UUID); do not create a new send. |
| Structured validation or permission rejection | Fix the named field or permission. Do not treat it as a transient transport failure. |

## DNS and webhook checks

Section link: https://www.stampwing.com/guides/stampwing-troubleshooting#dns-webhook

- Domain stays pending: compare every expected name/type/value against public DNS, including provider-added suffixes. Wait for caching, then inspect the next observed check.
- SPF reports multiple policies: keep one SPF policy at that name; do not add another TXT record with v=spf1.
- Webhook signature fails: use unaltered request bytes and the endpoint’s own secret, check the three webhook headers, and check server clock accuracy.
- Webhook cannot reach localhost: the hosted sender cannot reach your laptop’s loopback. Use a controlled public HTTPS endpoint when testing an actual integration.
- Repeated webhook: deduplicate the verified event identity in durable storage. Replaying the notification must not resend the original email.

## Make a useful, redacted support report

Section link: https://www.stampwing.com/guides/stampwing-troubleshooting#support-report

For a local installation, include a redacted startup or worker error and whether /api/health reports database ready. For an SDK problem, include a minimal synthetic request and the installed version. Contact the operator or support channel provided by your installation; this guide does not invent a public support address.

Copy and fill in; leave secret values out

```text
Stampwing setup report
Installation: local / operator-managed; origin only
Runtime / SDK version:
Project reference and Test or Live:
Step that failed:
UTC time:
HTTP status and error code:
Request ID:
Message UUID, if accepted:
Expected result:
Actual result:
Checks already completed:
Can it be reproduced with synthetic Test data?

Exclude credentials, message bodies, personal recipient data, and token URLs.
```

## Sources

Section link: https://www.stampwing.com/guides/stampwing-troubleshooting#sources

- [Stampwing API contract (implemented interfaces; deployment gates still apply)](https://www.stampwing.com/reference/openapi.json)

Developer documentation: https://www.stampwing.com/docs

Next step: [Check request fields and permissions](https://www.stampwing.com/guides/stampwing-api-reference)

## Related guides

- https://www.stampwing.com/guides/stampwing-quickstart
- https://www.stampwing.com/guides/stampwing-api-reference
- https://www.stampwing.com/guides/email-delivered-but-not-received

Editorial policy: https://www.stampwing.com/resources/editorial