Notifications aren't arriving

Symptom: a pipeline escalates (or aborts, or stops) and your configured notifications: channel — Telegram, Slack, a webhook — never receives anything. The run log almost always tells you which of these it is; check it before changing config.

1. Check the run log for the actual event first

Open the run in the UI and expand the Run log. Whatever happened is named there explicitly:

Event you’ll see	What it means
Notification sent: escalate → telegram (or similar, per channel)	It genuinely sent. If it still didn’t arrive, this is a delivery problem on the channel’s end (§4/§5 below), not a VectorStep problem.
[testing] Notification routed to log: escalate → would have been telegram	§2 below — the pipeline is stage: testing.
No notification event at all, anywhere in the log	§3 below — nothing actually escalated on this run.

2. stage: testing mutes every real channel, on purpose

If the pipeline is stage: testing (the default, and every pipeline starts here), every configured notification is forced through the log channel instead of the real one — Telegram, Slack, webhook, all of it — regardless of what’s actually configured. This is deliberate: testing activity should never look like a real page. The run log names this explicitly ([testing] Notification routed to log: ... → would have been telegram), with the template fully rendered, so you can confirm the content is right even though it didn’t go anywhere real.

Nothing further to fix here except promoting the pipeline once you’re actually ready — see Promote your pipeline to production. Once promoted, the exact same config starts reaching the real channel with no other change.

3. Nothing escalated — a healthy run sends nothing, correctly

notifications: reacts to a state transition — escalate, abort, stop, notify — never to a run simply completing successfully. A run that finishes cleanly has nothing to notify about, and correctly sends nothing, even in stage: production with everything configured correctly. If you were expecting a message and got silence, check the run’s own status first: if it says completed, this is why, not a bug. If you want a message on every run regardless of outcome, that’s a different mechanism — see executor: notify as an explicit last step, rather than the notifications: block.

4. The channel isn’t configured at all

Check the service’s startup logs:

docker compose logs vectorstep | grep -i "notifier configured\|notifier not configured"

Telegram notifier configured means notifications.telegram.bot_token and .chat_id both resolved to non-empty values at startup. Telegram notifier not configured — notifications will be skipped means one or both didn’t — almost always a missing or misspelled variable in .env, or a vectorstep.yaml/.env restart-order issue (a new .env value needs a real container recreate — docker compose up -d, not docker compose restart— to actually be picked up; see the same gotcha covered for artifact storage and live pricing elsewhere in this docs series).

5. Credentials are configured but invalid

A configured-but-wrong token is the quietest failure mode, because VectorStep can’t tell the difference between “not configured” and “wrong value” until it actually tries to send. Look for the channel’s own delivery error, logged at the moment of the real send attempt:

ERROR src.notifications.telegram Telegram API error: status=401 body={"ok":false,"error_code":401,"description":"Unauthorized"}

A 401 here means Telegram itself rejected the bot token — it’s invalid, revoked, or was mistyped when it was added to .env. Confirm the token independently of VectorStep before assuming anything else is wrong:

curl -s "https://api.telegram.org/bot<your-token>/getMe"
# {"ok":false,...} means the token itself is bad, not VectorStep's use of it

For Slack, the equivalent failure is usually a bot token missing the chat:write scope, or a channel_id the bot hasn’t been invited to — both surface as an API error in the same place in the logs, naming Slack’s own error code.

Where next

• Notifications — the full channel reference (log/telegram/slack/webhook) and executor: notify.
• Testing vs production stages — the complete list of what else stage: testing mutes besides notifications.
• Route escalations to a real channel — setting up Telegram from scratch, including getting a working bot token via @BotFather.