[v2.2.3 Docker] QR / instance linking flow unclear (cannot reliably get or use QR, but messages send OK

[NinoFortunato]

Welcome!

• Yes, I have searched for similar issues on GitHub and found none.

What did you do?

I'm running Evolution API with Docker using the atendai/evolution-api:v2.2.3 image on a local Windows 11 development machine (Docker Desktop).

I was able to:

• bring the stack up (PostgreSQL + Redis + evolution-api),
• hit the HTTP API from my own backend (SvelteKit),
• and successfully send at least one outgoing message from an instance called local-fiestas.

However, the QR / instance linking flow is not clear or reliable for me on this setup:

• I never managed to properly see or use the QR code for local-fiestas from the HTTP API,
• I relied on various examples/docs/tutorials, but I don't know what is the correct, supported way in v2.2.3 to get and use the QR for an instance created via HTTP when self‑hosting with Docker.

There are no code errors in my own system; the instance was created and a test message was sent, but I never had a clean, documented QR flow to link and manage the session.

---

Environment

• Evolution API image: atendai/evolution-api:v2.2.3 (Docker)
• OS: Windows 11
• Docker: Docker Desktop for Windows
• Database: PostgreSQL (Docker postgres:16-alpine)
• Cache: Redis (Docker redis:7-alpine)
• Use case: self‑hosted API on local machine, integrating with a SvelteKit backend

---

Docker setup

docker-compose.yml

services:
  postgres:
    image: postgres:16-alpine
    container_name: evolution_postgres
    restart: always
    environment:
      POSTGRES_DB: evolution
      POSTGRES_USER: evolution
      POSTGRES_PASSWORD: evolutionpass
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - evolution-net
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U evolution -d evolution"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    container_name: evolution_redis
    restart: always
    command: redis-server --appendonly yes
    volumes:
      - redis_data:/data
    networks:
      - evolution-net
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  evolution-api:
    image: atendai/evolution-api:v2.2.3
    container_name: evolution-api
    restart: always
    ports:
      - "8080:8080"
    env_file:
      - .env
    volumes:
      - evolution_store:/evolution/store
      - evolution_instances:/evolution/instances
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - evolution-net

volumes:
  postgres_data:
  redis_data:
  evolution_store:
  evolution_instances:

networks:
  evolution-net:
    driver: bridge
.env
text
# Authentication
AUTHENTICATION_API_KEY=**

# Server
SERVER_PORT=8080
SERVER_URL=http://127.0.0.1:8080

# WhatsApp / Baileys
CONFIG_SESSION_PHONE_VERSION=2.3000.10216511034
CONFIG_SESSION_DEFAULT_DEVICES=1

# PostgreSQL
DATABASE_ENABLED=true
DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI=postgresql://evolution:evolutionpass@postgres:5432/evolution?schema=public

# Redis / Cache
CACHE_REDIS_ENABLED=true
CACHE_REDIS_URI=redis://redis:6379

# Integrations disabled
N8N_ENABLED=false
CHATWOOT_ENABLED=false
OPENAI_ENABLED=false
TYPEBOT_ENABLED=false
RABBITMQ_ENABLED=false
WEBHOOK_ENABLED=false

# Optional stability
DEL_INSTANCE_ON_DISCONNECT=false
STORE_MESSAGES=true
Logs
docker logs evolution-api at startup:

text
Deploying migrations for postgresql
Database URL:

> evolution-api@2.2.3 db:deploy
> node runWithProvider.js "rm -rf ./prisma/migrations && cp -r ./prisma/DATABASE_PROVIDER-migrations ./prisma/migrations && npx prisma migrate deploy --schema ./prisma/DATABASE_PROVIDER-schema.prisma"

Environment variables loaded from .env
Prisma schema loaded from prisma/postgresql-schema.prisma
Datasource "db": PostgreSQL database "evolution", schema "public" at "postgres:5432"

49 migrations found in prisma/migrations


No pending migrations to apply.
Migration succeeded

> evolution-api@2.2.3 db:generate
> node runWithProvider.js "npx prisma generate --schema ./prisma/DATABASE_PROVIDER-schema.prisma"

Environment variables loaded from .env
Prisma schema loaded from prisma/postgresql-schema.prisma

✔ Generated Prisma Client (v6.3.0) to ./node_modules/@prisma/client in 647ms

> evolution-api@2.2.3 start:prod
> node dist/main

[Evolution API]    v2.2.3  212   -  Fri Jan 23 2026 02:13:20     VERBOSE   [CacheEngine]  [string]  RedisCache initialized for groups
[Evolution API]    v2.2.3  212   -  Fri Jan 23 2026 02:13:20     VERBOSE   [CacheService]  [string]  cacheservice created using cache engine: Gt
[Evolution API]    v2.2.3  212   -  Fri Jan 23 2026 02:13:21     VERBOSE   [CacheEngine]  [string]  RedisCache initialized for instance
[Evolution API]    v2.2.3  212   -  Fri Jan 23 2026 02:13:21     VERBOSE   [CacheService]  [string]  cacheservice created using cache engine: Gt
[Evolution API]    v2.2.3  212   -  Fri Jan 23 2026 02:13:21     VERBOSE   [CacheEngine]  [string]  RedisCache initialized for baileys
[Evolution API]    v2.2.3  212   -  Fri Jan 23 2026 02:13:21     VERBOSE   [CacheService]  [string]  cacheservice created using cache engine: Gt
[Evolution API]    v2.2.3  212   -  Fri Jan 23 2026 02:13:21     INFO   [WA MODULE]  [string]  Module - ON
[Evolution API]    v2.2.3  212   -  Fri Jan 23 2026 02:13:21     VERBOSE   [Redis]  [string]  redis connecting
[Evolution API]    v2.2.3  212   -  Fri Jan 23 2026 02:13:21     VERBOSE   [Redis]  [string]  redis ready
[Evolution API]    v2.2.3  212   -  Fri Jan 23 2026 02:13:21     INFO   [PrismaRepository]  [string]  Repository:Prisma - ON
[Evolution API]    v2.2.3  212   -  Fri Jan 23 2026 02:13:21     LOG   [SERVER]  [string]  HTTP - ON: 8080
create instance {
  instanceName: 'local-fiestas',
  integration: 'EVOLUTION',
  pairingCode: false,
  qrcode: true
}
[Evolution API]  [dd69e5fb-ebd1-420c-8e02-480e8a610870]  v2.2.3  212   -  Fri Jan 23 2026 02:37:10     LOG   [ChannelStartupService]  [object]
{
  key: {
    fromMe: true,
    id: '75f60ed6-1b95-441b-8394-517f91a5ce87',
    remoteJid: '584123306484@c.us'
  },
  message: {
    conversation: '✅ Prueba Evolution v2.2.3 /instance. Reserva local-fiestas OK.',
    quoted: undefined
  },
  messageType: 'conversation',
  messageTimestamp: 1769146631,
  webhookUrl: undefined,
  source: 'unknown',
  instanceId: 'dd69e5fb-ebd1-420c-8e02-480e8a610870'
}
So the instance local-fiestas is created and can send messages.

The problem (QR / linking flow)
Even though the instance is created and can send a message once linked, the main problem I have and want to report is:

I never managed to have a clear and reliable QR flow with this Docker setup on v2.2.3.

Specifically:

I could not find a stable/documented way to get the QR code via HTTP for local-fiestas (using the official v2 docs and various tutorials).

I could not consistently see and use the QR to link my account when testing from my own backend and local environment.

There are no errors in my own application code; the problem is understanding and following the correct QR / linking flow for this image/version.

In other words: once the instance somehow gets linked, sending messages works (as seen in the logs), but I do not know the correct, official HTTP flow on v2.2.3 Docker to:

create the instance,

get the QR code (and refresh if needed),

and be sure that the device is properly linked in a reproducible way.

### What did you expect?

From the Evolution API v2 docs, I expected a documented flow like:

Create an instance via HTTP.

Retrieve the QR code via a clear endpoint or via a documented webhook event (QRCODE_UPDATED with base64).

Scan the QR with the WhatsApp app on my phone.

See the instance status move to a connected/ready state.

Use the send message endpoints reliably. [doc.evolution-api.com](https://doc.evolution-api.com/) [web:5][web:22]




### What did you observe instead of what you expected?

Instead of having a clear, documented flow to get and use the QR code for my instance, I was never able to reliably see or handle the QR from the HTTP API in this Docker setup (v2.2.3).

I could create the instance and I see in the logs that at least one outgoing message was sent from `local-fiestas`, so the instance can work once linked. However, I never had a stable or well-documented way (for this version/image) to:

- obtain the QR code via HTTP,
- refresh or manage that QR,
- and confirm that the device was properly linked in a reproducible way from my local environment.

In practice, this means I can’t confidently reproduce the full “create instance → get QR → link device → send messages” flow on `atendai/evolution-api:v2.2.3` using Docker on my machine.


### Screenshots/Videos

<img width="1920" height="1080" alt="Image" src="https://github.com/user-attachments/assets/fd8c71fb-859e-417e-866a-d1a4f670b660" />
<img width="1920" height="1080" alt="Image" src="https://github.com/user-attachments/assets/37832fc6-cb05-4c45-9a4d-fd3f94d9ce4c" />

### Which version of the API are you using?

v2.2.3 using Docker

### What is your environment?

Windows

### Other environment specifications

Evolution API v2.2.3 using Docker

### If applicable, paste the log output

Deploying migrations for postgresql
Database URL:

> evolution-api@2.2.3 db:deploy
> node runWithProvider.js "rm -rf ./prisma/migrations && cp -r ./prisma/DATABASE_PROVIDER-migrations ./prisma/migrations && npx prisma migrate deploy --schema ./prisma/DATABASE_PROVIDER-schema.prisma"

Environment variables loaded from .env
Prisma schema loaded from prisma/postgresql-schema.prisma
Datasource "db": PostgreSQL database "evolution", schema "public" at "postgres:5432"

49 migrations found in prisma/migrations

No pending migrations to apply.
Migration succeeded

> evolution-api@2.2.3 db:generate
> node runWithProvider.js "npx prisma generate --schema ./prisma/DATABASE_PROVIDER-schema.prisma"

Environment variables loaded from .env
Prisma schema loaded from prisma/postgresql-schema.prisma

✔ Generated Prisma Client (v6.3.0) to ./node_modules/@prisma/client in 647ms

> evolution-api@2.2.3 start:prod
> node dist/main

[Evolution API]    v2.2.3  212   -  Fri Jan 23 2026 02:13:20     VERBOSE   [CacheEngine]  [string]  RedisCache initialized for groups
[Evolution API]    v2.2.3  212   -  Fri Jan 23 2026 02:13:20     VERBOSE   [CacheService]  [string]  cacheservice created using cache engine: Gt
[Evolution API]    v2.2.3  212   -  Fri Jan 23 2026 02:13:21     VERBOSE   [CacheEngine]  [string]  RedisCache initialized for instance
[Evolution API]    v2.2.3  212   -  Fri Jan 23 2026 02:13:21     VERBOSE   [CacheService]  [string]  cacheservice created using cache engine: Gt
[Evolution API]    v2.2.3  212   -  Fri Jan 23 2026 02:13:21     VERBOSE   [CacheEngine]  [string]  RedisCache initialized for baileys
[Evolution API]    v2.2.3  212   -  Fri Jan 23 2026 02:13:21     VERBOSE   [CacheService]  [string]  cacheservice created using cache engine: Gt
[Evolution API]    v2.2.3  212   -  Fri Jan 23 2026 02:13:21     INFO      [WA MODULE]      Module - ON
[Evolution API]    v2.2.3  212   -  Fri Jan 23 2026 02:13:21     VERBOSE   [Redis]          redis connecting
[Evolution API]    v2.2.3  212   -  Fri Jan 23 2026 02:13:21     VERBOSE   [Redis]          redis ready
[Evolution API]    v2.2.3  212   -  Fri Jan 23 2026 02:13:21     INFO      [PrismaRepository] Repository:Prisma - ON
[Evolution API]    v2.2.3  212   -  Fri Jan 23 2026 02:13:21     LOG       [SERVER]        HTTP - ON: 8080

create instance {
  instanceName: 'local-fiestas',
  integration: 'EVOLUTION',
  pairingCode: false,
  qrcode: true
}

[Evolution API]  [dd69e5fb-ebd1-420c-8e02-480e8a610870]  v2.2.3  212   -  Fri Jan 23 2026 02:37:10     LOG   [ChannelStartupService]
{
  key: {
    fromMe: true,
    id: '75f60ed6-1b95-441b-8394-517f91a5ce87',
    remoteJid: '584123306484@c.us'
  },
  message: {
    conversation: '✅ Prueba Evolution v2.2.3 /instance. Reserva local-fiestas OK.',
    quoted: undefined
  },
  messageType: 'conversation',
  messageTimestamp: 1769146631,
  webhookUrl: undefined,
  source: 'unknown',
  instanceId: 'dd69e5fb-ebd1-420c-8e02-480e8a610870'
}


### Additional Notes

_No response_

[NinoFortunato]

“I’m using Evolution 2.2.3 with Manager v2, Baileys channel. The QR code appears, but when I scan it from WhatsApp, I get the error ‘could not link, please try again later’. I see that in issue #1429 several people are reporting the same issue on 2.2.3. Is there a recommended version or value for CONFIG_SESSION_PHONE_VERSION that works reliably now?”