instance creation fails with Foreign key constraint violated on the constraint: Setting_instanceId_fkey on a completely fresh install (reproducible on 2.4.0, 2.4.0-rc2, and homolog)

[faisalriazz]

Yes, I have searched for similar issues on GitHub and found none that match exactly, though the stack trace pattern resembles older closed reports (#2423, #2218) which appear to be a different underlying trigger (those were tied to existing/legacy data, not fresh installs).

What did i do?

Created a brand new WhatsApp instance (Baileys integration) on a completely fresh install — new Postgres database, new Redis cache, new Docker volumes, no prior data of any kind. This was reproduced independently in two separate environments:

1. Production VM (Ubuntu, Docker Compose with Traefik + Postgres 15 + Redis 7), after fully dropping and recreating the evolution database, flushing Redis, and deleting/recreating the evolution_instances volume.
2. Local machine (Docker Desktop, isolated docker compose stack with its own fresh Postgres 15 + Redis 7, no shared state with the VM at all), using the homolog tag.

In both cases, instance creation was attempted immediately after a clean, verified startup (Prisma migrations completed successfully, license activated where applicable, no prior errors in logs).

Instance creation was attempted two ways, both failing identically:

• Via the Manager UI "New instance" form (Name: TestWA, Channel: Baileys, auto-generated Token)
• Via direct API call:

curl -s -X POST https://<host>/instance/create \
  -H "Content-Type: application/json" \
  -H "apikey: <valid_global_api_key>" \
  -d '{"instanceName": "TestInstance", "qrcode": true, "integration": "WHATSAPP-BAILEYS"}'

What did you expect to happen?

The instance should be created successfully and return instance details + QR code, as documented.

What actually happened?

The request fails with a 400 Bad Request, and the instance is immediately auto-removed:

{"status":400,"error":"Bad Request","response":{"message":["\nInvalid `a.integrationSession.update()` invocation in\n/evolution/dist/main.js:202:11516\n... Foreign key constraint violated on the constraint: `Setting_instanceId_fkey`"]}}

Corresponding container logs:

[Evolution API] ERROR [InstanceController]
Invalid `a.integrationSession.update()` invocation in
/evolution/dist/main.js:202:11516
Foreign key constraint violated on the constraint: `Setting_instanceId_fkey`
[Evolution API] WARN [WAMonitoringService] Instance "undefined" - REMOVED

Note the instance name resolves to "undefined" in the removal log line, suggesting the instance record is not fully persisted/committed before downstream code (processMessages → integrationSession.update) attempts to write a related Setting row referencing its instanceId — resulting in a race condition / ordering bug where the FK target doesn't exist yet.

This is 100% reproducible — every single instance-creation attempt on a fresh DB fails with this exact error, across all three versions tested.

Environment

• Versions tested (all reproduce identically):
  • evoapicloud/evolution-api:2.4.0 (stable-tagged, production VM)
  • evoapicloud/evolution-api:2.4.0-rc2 (implied same code path)
  • evoapicloud/evolution-api:homolog (pulled ~July 2026, local test)
• Database: PostgreSQL 15 (official postgres:15 image), freshly created database each time, 59 migrations applied successfully with no errors (db:deploy reports "Migration succeeded")
• Cache: Redis 7 (official redis:7 image), FLUSHALL run before each test, DBSIZE confirmed 0 before instance creation attempt
• Deployment: Docker Compose, both behind Traefik (production) and standalone with direct port exposure (local test) — same error in both, ruling out reverse proxy/networking as a factor
• Integration type: WHATSAPP-BAILEYS
• No chatbot/integration env vars enabled (WEBHOOK_EVENTS_TYPEBOT_START=false, no Chatwoot/OpenAI/Typebot configuration present)
• License: Activated successfully prior to testing on 2.4.0 ([Licensing] License activated successfully in logs) — not a licensing-related failure

Steps to reproduce (minimal)

1. Fresh Postgres 15 + Redis 7 containers, no prior data.
2. Start evoapicloud/evolution-api:homolog (or 2.4.0) pointed at the fresh DB/Redis.
3. Confirm clean boot: migrations succeed, no errors, server listening.
4. Attempt to create any new instance via /instance/create or the Manager UI "New instance" form.
5. Observe immediate 400 error with the FK violation above; instance is auto-removed.

Additional context

This was discovered while separately investigating an unrelated, also-unresolved issue: intermittent message delivery failures (status: 'ERROR' on messages.update, preceded by Closing session: SessionEntry in logs) for contacts using WhatsApp's @lid addressing — which appears to match the tracked meta-issue #1872. That investigation led to testing 2.4.0/homolog specifically for the @lid fix in #2544, which is how this separate instance-creation bug was found. Rolling back to v2.3.7 avoids this specific FK bug but does not have the @lid fix, so there's currently no available tag that has neither issue.