Evolution API instance stuck on “connecting”: the usual causes

An instance stuck on “connecting” means Evolution API is trying to reach WhatsApp and cannot, or that the service restarts before it finishes. The most common cause, according to people who install it, is a Baileys version that does not fit what WhatsApp is doing at the moment. But there are others, and the logs tell you which. Always read them first.

Read the logs first

1 See whether the service is up. docker compose ps shows whether the API is running or restarting non-stop. Restarts in a row are the clearest clue.
2 Follow the logs. docker compose logs -f, in the project folder, while you ask for the connection. Look for the first error line, not the last: the rest are consequences.
3 Note the image version you are running. You will need it to read the release notes and the project’s known issues.

The causes, most likely first

Cause How to recognise it What to do
Incompatible Baileys version The connection closes right after the QR is scanned, or the service restarts in a loop, with no network error. Read the release notes and open issues in the project’s repository. Move to the version they name as correct, or go back to the last one that worked. Pin the image version.
Old or damaged session The instance existed, stopped connecting, and the QR does not appear or does not work. Delete the instance and create it again, scanning a new QR. See connecting with the QR and reconnecting.
The server cannot reach WhatsApp The logs show network or name-resolution errors. Test outbound traffic, for example with curl -I https://web.whatsapp.com, and check the outbound firewall and DNS.
Wrong server clock Certificate or secure-connection errors with no other cause. Check the server date and time with timedatectl and turn on synchronisation.
Out of memory The container vanishes with no application error. See common VPS errors. Cut what runs beside it, or add memory.
Database or Redis unreachable The API complains about the database connection and restarts. Check passwords and service names. See PostgreSQL and Redis.
The number was restricted or banned The phone shows a WhatsApp notice. No QR works. It is the Baileys risk. See the risk and the rules. Do not keep retrying.
Do not update blindly. Moving to the newest image may fix the problem, but it may also bring another and touch your data. Make a copy first (see updating and backing up) and change one thing at a time.

A sequence that saves time

1 Logs and service state, as above.
2 Network and clock of the server, which are quick to rule out.
3 Image version against the project’s notes.
4 A new instance with a new QR, to rule out a damaged session.
5 Another test number, to learn whether the problem is the server or the number.
If you ask a community or the project for help, bring the image version, the log lines of the first error and what you have already tried. Remove anything secret (the API key, tokens, numbers). Interweb support looks after the VPS and the network, but does not install or repair Evolution API: see the Support Policy.

Is the server short of memory or disk? See which VPS gives you room.

See VPS servers

SEE ALSO

Connecting with the QR code and reconnecting

Updating and backing up Evolution API

Common VPS errors

RECOMMENDED PRODUCT

Web hosting with cPanel

Domain and SSL included, daily backups and the panel you already know. from $5.36/mo (3-year plan, with coupon)

See plans
  • 0 Users Found This Useful
Was this answer helpful?

Related Articles

Putting WhatsApp on your site: the link, the button and the ready-written message In Mozambique, WhatsApp is where business conversations happen. A contact form gives you a message somebody reads tomorr...
Ordinary WhatsApp, Business or the Cloud API: which suits your business We call four different things «WhatsApp», and choosing the wrong one costs money or costs the number. One is free and is...
WhatsApp for business: the risks, and the practices that avoid them WhatsApp has become the sales channel for many businesses in Mozambique, and that brought a risk few weigh up: the numbe...
WhatsApp, e-mail or SMS: advantages, disadvantages, risks and who each is for WhatsApp, e-mail and SMS all exist to talk to customers, and the question «which is best» has no answer - because they a...
Ordinary WhatsApp for business: advantages, disadvantages, risks and who it is for The app almost everyone starts with - the same one used personally - put to work for the business. It is the commonest o...
Securing Evolution API: key, HTTPS and the open port An exposed Evolution API is an open door to your WhatsApp number: whoever reaches it and holds the key sends messages in...