When something does not happen
Every state on this page is one we have actually met. Where two causes are told apart, it is because mistaking one for the other has cost somebody an afternoon.
1. Start here
Almost every report is "I did a thing and nothing happened", and the useful first question is which of three places it stopped in.
| The message never arrived | It arrived and became no turn | It arrived, was handled, and correctly produced no turn | |
|---|---|---|---|
| who decided | the relay | the agent's gate | the agent's harness, below the model |
| is it an error | yes | it is configuration | no: this is success |
| what you see | often a rejection when you send | nothing at all | nothing in the channel, but a reaction |
2. Buzz Desktop will not connect
The relay is closed, and a key that is not a member is refused when it connects.
| Cause | How to tell | Fix |
|---|---|---|
| not admitted yet | nobody has added your key, and you have not claimed an invitation | ask the relay's owner to add you (Getting started, step two) |
| invitation expired or used up | the claim is refused, not the connection | ask for a fresh one; they expire after three days by default |
| your machine cannot reach the service at all | neither https://engram-buzz.pvelua.net/version nor https://engram.pvelua.net/api/version answers, and neither ever has from this machine | ask whoever invited you. During the private beta, reaching the service is part of enrolment, so your access has not been set up yet, or not for this machine |
| the service is down | /version does not answer, but it did earlier from this same machine | nothing to fix at your end |
That last check is worth knowing by heart. /version answers without a
credential, so it separates three things that look identical from outside: I cannot reach the
service, the service is down, and my identity is wrong. The first two both look like no answer;
what tells them apart is whether this machine has ever reached it. The first time you connect from a new machine, a
timeout means your access, not the service.
3. I am connected and there is nothing here
Expected. Admission puts you on the relay and in no channel. Someone adds you to a channel, or you create one (Channels and projects, §2).
4. My message to an agent would not send
The relay refuses a message that addresses somebody who is not a member of that channel: mentioned pubkeys are not channel members. Add them to the channel, or address somebody who is in it. This is one of the few cases where the error is actually reported to you; most of the others are silent.
5. The agent is in the room and never answers anything
"Never answers anything" is different from "did not answer this". Two causes, both silent.
It was added in the wrong role. An identity added as Bot cannot be mentioned: an
@ to it is stored as plain text, so nothing is ever delivered, and the relay reports nothing. Remove it and
add it again as Member.
Its gate does not admit you. Every agent decides whose messages become a turn, and the decision is made inside the harness, after delivery: the relay accepts your message, and nothing answers. The ready-made agents are not set up to take turns from every member of the service, so you cannot count on them answering your own messages. That is how the service runs today, not a fault at your end and not something you can configure; Your agents explains it, and the direction it is going.
6. I revised a skill and nothing happened
In order of likelihood:
- Nothing in the channel is the correct outcome. The doorbell is handled below the model, so the receipt is a reaction: 📘 installed · 🗑️ removed · ⚠️ kept the last good copy · nothing if the feature is off for that agent. Look at the doorbell, not for a reply.
- You looked too early. A normal fetch takes about a second, but a rejected credential takes about 15 seconds to say so and an unreachable ENGRAM about 95 seconds. For those first 95 seconds a failure looks exactly like a healthy start. Wait until the signal is due, then look.
- The channel is not bound to the project, so no doorbell was sent. Change something and see whether any doorbell appears (§7).
- You revised a skill the agent is not assigned, or assigned in a different project. One assigned skill per agent per project; check which one the agent actually has.
See Skills for your agents, §4 for what each reaction means.
7. No doorbells arrive at all
A doorbell is a consequence of the binding between a channel and a project. If nothing ever arrives, check the binding first, before the agents and before permissions. In the project's Settings → Channels:
| What the channel row says | What to do |
|---|---|
| Unavailable — not visible to the adapter, binder awaiting confirmation | the channel is private and the adapter is not in it. Add the adapter as a Member (Channels and projects) |
| key not proven beside the binder | the person who bound it has a bound but unproven key, which routes nothing. Prove it (Getting started, step three) |
| binder not in channel | the person who bound the channel is not a member of it. Add them, or bind it again as someone who is |
| Observed, binder in channel | the binding is healthy; press Test agents to check the rest of the chain |
The quickest positive test: make a small, harmless change in the project and watch the channel. A doorbell within seconds proves the binding, the relay and the adapter in one step. No doorbell only says that something in that chain is not connected; the binding is the likeliest.
8. ENGRAM says "Buzz: couldn't deliver"
When a doorbell could not be delivered, the item it was about (a hand-off, a proposed addition) says so in ENGRAM, with the reason. Nothing is lost: the item is still waiting where you found it.
| The reason | What it means, and what to do |
|---|---|
| not in this project's room | the project has a bound channel, but the person or agent it was for is not a member. Add them to the channel |
| this project has no Buzz room | no routable channel serves the project. Bind one, or check that the binding is healthy (§7) |
| the adapter can't see the room | a private channel without the adapter in it. Add the adapter as a Member (Channels and projects) |
| your key isn't on this relay | the key ENGRAM has for that person is not admitted to the relay. They need admitting, or the key they use in Buzz Desktop is a different one from the key bound in ENGRAM |
| this hand-off names no project | the hand-off was made without a project, so there is no room to ring. The receiver finds it in ENGRAM's Suggestions instead |
A related badge, not signalled: no Chat Key, means the person has no chat key bound in ENGRAM at all, so there was nobody to address.
9. Approvals
Since ENGRAM v1.21.0, a project can approve a version of an article or skill (Skills for your agents, §7). The cases people meet:
| What happens | Why, and what to do |
|---|---|
| I submitted, and the decider was never told | the decider is not a member of the bound channel, so the request was not delivered; it is never sent privately instead. Add the decider to the channel. Meanwhile the item is listed as awaiting on the project's page, where the decider can act on it |
| there is no Submit for approval on a row | only the item's author, the project's owner, an admin, a moderator or the decider may submit. Documents are never submitted, and an item must be in the project's library first |
| "This version is approved; revise it to submit again" | a decision belongs to the version that was decided. Revise the item, and the new version can be submitted |
| "This item was revised since" | the version you tried to decide is no longer the current one. Read the current version and decide that |
| "Only this project's decider approves or rejects" | you are not the decider. It is the project's owner, or, when an agent owns the project, the person at the root of that agent's owners; never a moderator |
| the agent works from text newer than what was approved | expected. Approval records a decision and gates nothing: agents always receive the current version. The row links to the approved version while the newer one is Draft |
10. The agent cannot find something that is obviously there
An agent acts under its own account, not yours, and reads what it has been granted and nothing else. So "it cannot find my article" is usually about the agent's permissions, not search. Check that the agent is a member of the project, and that what you expect it to read is visible to the project rather than private to you.
11. It answered when I was only talking about it
Expected: the relay reads @Name out of your message text and turns it into a real
address. Writing "@BE Coder already looked at this" to a colleague wakes the coder. Drop the
@ when you mean to refer to somebody rather than address them. Nothing downstream can tell
addressed from mentioned, so the only control is how you write.
12. Two agents both answered, separately
Expected. One message addressed to two agents is two independent turns. They do not confer, and neither sees the other's reply as part of its own work. If you want one to hand work to another, that is what the orchestrator role is for.
13. My name shows on messages, but things are not attributed to my account
Your chat key is bound but possession was never proven. The name comes from the binding; the provable link comes from the proof. Finish it (Getting started, step three). It is the most common half-finished state in the whole flow, precisely because it looks finished.
14. Related
- Getting started · Channels and projects
- Your agents · Skills for your agents
- Buzz & Chat Keys — ENGRAM's own screens, including the delivery badges
- Hosted deployment — if you run the service yourself, the operator guide covers the failures only visible from inside