Troubleshooting

Task-oriented fixes for the problems you'll actually hit: a blank formula, an Excel error code, an agent that won't reconnect, and enrollment failures — plus where to look for more detail.

My formula is blank

By far the most common surprise, and almost always the same cause: you haven't published. Editing a connection, function, ribbon button, or taskpane only changes the environment's working draft — it does not reach Excel until you deliberately publish it.

Open the environment's Versions page and check the banner. An amber "unpublished changes" banner means the draft and the live version differ.
Click Save version, keep "Make this version live" checked, and save.
Recalculate the workbook. The formula should now resolve.

If the banner is blue (nothing unpublished) and the formula is still blank, confirm the function actually exists in the environment you're testing against — non-production environments suffix the namespace (=NAMESPACE_DEV.MODULE.FN(…) for Development, _QA for QA, and so on), so a workbook wired to the wrong environment's namespace will never find the function. See Versions for the full draft/live model.

Excel error codes

These are Excel's own error values, shown in the cell — not something ConnXL invents. Here's what each one means when it comes from a ConnXL function, and what to check.

Field	Type	Description
`#GETTING_DATA`Optional	`transient`	Normal, not an error: an async function is still waiting on the agent. It resolves on its own once the call completes. Persists indefinitely only if the agent is unreachable or the call hangs — check the agent is online and the connection it depends on responds.
`#SPILL!`Optional	`blocked spill`	A function that returns multiple rows/columns needs empty cells to spill into, and something occupies that range. Clear the cells below and to the right of the formula, or move the formula somewhere with room.
`#BUSY!`Optional	`stale registration`	Excel is stuck on an old custom-functions registration for the namespace — usually left over from a previous manifest version. Fully close Excel, clear its add-in cache, and reopen (Windows: delete the contents of `%LOCALAPPDATA%\Microsoft\Office\16.0\Wef\`; on the web, hard-refresh). Re-sideloading after a manifest change (a new ribbon button, icon, or ExecuteFunction action) is the usual trigger.
`#NAME?`Optional	`unrecognized function`	Excel doesn't recognize the formula name at all. Check the namespace (remember non-production environments are suffixed, e.g. NAMESPACE_DEV), the module and function spelling, and that the manifest for this environment has actually been installed — a manifest change (new function names show up via re-generated metadata, but a namespace or add-in identity change needs a fresh sideload) requires re-installing.
`#VALUE!`Optional	`bad argument`	The function received an argument of the wrong type or an invalid value — a text value where a number was expected, an out-of-range parameter, or a required argument left blank. Check the function's parameter types against what the cell references actually contain.

A custom error message still shows as a standard code

A function can throw a specific error (invalid value, division by zero, a name it doesn't recognize) and Excel always renders it as one of its own codes — the underlying message isn't lost, though: hover the cell's error indicator, or check the function's test run in the dashboard, to see the actual text.

The agent won't reconnect

"No replicas serving this environment yet" — this environment's agent has never connected. Double-check the environment variables on the host (CONNXL_BACKEND_URL, the enrollment token or attestation vars) and that the host can reach the backend outbound.
"No replicas are currently reporting" — the agent has connected before but isn't right now. Check the process is actually running on the host, and that outbound network access to the backend hasn't been blocked since the last successful connection.
Flagged offline after ~10 minutes of silence — an agent that stops heart-beating is marked offline and raises an agent_offline alert automatically; it clears the moment the agent reconnects. See Alerts.
A specific replica keeps reconnecting and you don't want it to — from the Agent page's instances list, Evict that replica. Eviction drains it and blocks its instance id from reconnecting with the environment's certificate; Restore lifts the block if you evicted the wrong one.

Certificate / enrollment failures

The agent's only credential is its mTLS certificate, obtained once at enrollment. Failures here are almost always one of:

"Enrollment token invalid or already used" — tokens are single-use and consumed the moment an agent successfully enrolls with them. Mint a fresh token from the environment's Agent page (a new token supersedes any unused one still outstanding) and set it before restarting.
Wrong add-in or environment id — the cloud-attestation enrollment path (CONNXL_ENROLL_ATTESTATION) reads CONNXL_ADDIN_ID/CONNXL_ENV_ID directly; a mismatched id enrolls against the wrong environment (or fails outright). Copy both from the Agent page you're enrolling.
Cloud attestation rejected — the instance's cloud identity (account/project/subscription, optionally region-pinned) isn't on the environment's Trusted cloud identities allowlist. Add a rule under the Agent page's Security tab for the provider and account the instance actually runs in.
Taskpane/functions won't load, but the agent is running — Office requires HTTPS. In the default edge mode the agent serves plain HTTP on :3000 and relies on a TLS-terminating load balancer in front; expose it directly on HTTP and Excel rejects the untrusted origin. In CONNXL_TLS_TERMINATION=agent mode the agent needs cert.pem/key.pem beside the binary to serve the add-in surface — without them it logs a warning and serves nothing to Excel (backend link, telemetry and heartbeat still run). This cert.pem/key.pem pair is a different pair from the mTLS one above; see the callout below.
Agent boots but every backend call fails auth — check CONNXL_MTLS_CERT/CONNXL_MTLS_KEY actually point at writable paths and haven't been pointed at the Office-facing cert.pem/key.pem by mistake.

Two certificate pairs, two different jobs

cert.pem/key.pem beside the binary are for Excel to trust the agent's own HTTPS endpoint — and only apply when CONNXL_TLS_TERMINATION=agent (in the default edge mode the load balancer holds that certificate instead). CONNXL_MTLS_CERT/CONNXL_MTLS_KEY are where the agent stores the certificate it enrolls for, to authenticate itself to the backend, always. Mixing them up is the single most common enrollment complaint — see Mutual TLS for the full lifecycle.

Where to look

When the checks above don't explain it, pull more signal directly from the agent:

Agent process logs — the Agent page's diagnostics panel fetches a live tail of the agent's own process log (not analytics — its internal debug/info/error lines), which is usually the fastest way to see the actual exception behind a failing function. See Logs & exports for how it differs from the usage/telemetry Logs page.
Run diagnostic — a one-click agent self-check from the same panel; useful before opening a support ticket.
Report health — forces a fresh CPU/memory/disk snapshot instead of waiting for the next scheduled one.
The health timeline and open-alert banner on the Agent page — for resource-pressure issues (CPU/memory/disk trending toward the warning or critical threshold) rather than a specific function failing.

Logs & exports

Usage analytics and the agent process-log viewer.

Versions

The draft/live model behind the most common "it's blank" issue.