Troubleshooting

arcy.js never throws into your app. Every problem it hits, a bad call, a blocked script, a dropped attribute, becomes a console.warn prefixed with [arcy] instead of an exception. Start by checking your browser console for one of those before anything else: it almost always names the exact problem.

Check the console for [arcy] Failed to load. ARCY is disabled. first. That means the script itself never loaded, most commonly because:

An ad blocker or a strict Content Security Policy blocked the request. Check your script-src and connect-src directives if you have a CSP.
The page navigated away before the script finished loading.

If you don't see that message, arcy.js loaded but didn't mount. Look for:

[arcy] The page has no <body> to mount into yet. The widget will not render.

This means init() ran before <body> existed, usually a script placed in <head> without defer or async. Move the script tag before the closing </body> tag, or run arcy.init(...) from code that only executes after the DOM is ready.

[arcy] This ARCY surface is already on this page. Ignoring the second mount.
[arcy] Another copy of ARCY is already on this page. Ignoring this one.

This means the snippet is installed twice, most commonly the NPM path and the HTML path both present on the same page, or the HTML snippet pasted into two different places (a layout template and a tag manager, for example). Pick one install path and remove the other.

"Verify installation" says "No traffic yet"

arcy.init() never reached your token's environment. In order of likelihood:

The page calling arcy.init() was never actually loaded in a browser, only checked into your codebase. Open the real page and reload it while Verify installation is watching.
The token in init() doesn't match the environment you're checking. Copy it again from that environment's Settings > Installation page. Every environment has its own token.
A network error is silently swallowing the call. Check your browser's network tab for the request that init() makes and see what it returns.

"Verify installation" says "Wrong environment token"

Traffic is arriving, but it's carrying a token that belongs to a different environment. This is almost always a snippet copied from the wrong environment's Installation page, for example pasting the Staging snippet into a Production deploy. Use the environment switcher in the dashboard sidebar to open the environment you actually want, copy its snippet from Settings > Installation, and reinstall.

"Verify installation" says "Origin not verified"

The token is correct, but the request came from a domain that hasn't been proven for this app. Verify installation names the exact refused origin. If that's a domain you own, add and verify it (a DNS TXT record, checked once per app), then assign it to the environment under Agent > Origins. localhost never needs this: it's trusted everywhere so local development works with no setup.

"Verify installation" says "Identity verification failed"

Sessions are arriving, but the signature you pass as userHash doesn't verify against the Secret on file for this environment. The install works; every affected session is served as anonymous instead of identified, which is why attributes and personalization silently stop working for those users while this is broken.

Re-check your signing code against Enforce identity verification: the recipe is HMAC-SHA256 of the exact string you pass to identify(), keyed with the environment's Secret, hex encoded. The most common cause is a type mismatch: if your user ids are integers and you call arcy.identify(String(user.id)), you must sign String(user.id), not the raw number. A signature over 42 will not verify a call identifying "42".

If you just rotated the Secret, signatures made with the previous one still verify for 24 hours, so a stale deploy shouldn't be the cause unless the rotation is older than that.

A custom attribute isn't showing up anywhere

Check the unknown attributes section of Verify installation first: an attribute key that arrives without being declared is dropped and named there, never silently stored. In the console, a dropped attribute also produces:

[arcy] identify() dropped "some_key": an attribute must be a string, number,
boolean, null, or an array of strings.

Two different causes produce the same symptom:

The key was never declared. Add it under Agent > Attributes, then send it again. Nothing is backfilled for traffic that already arrived undeclared.
The value's shape isn't one arcy.js can forward at all (a nested object, a function, a Date). Flatten it to a string, number, boolean, null, or an array of strings before passing it to identify().

`identify()` or `updateUser()` seems to do nothing

Check the console for:

[arcy] identify() needs a user id. Ignoring the call.
[arcy] identify() was called before init(). Ignoring.

The first means the user id argument was empty, undefined, or not a string. The second means identify() ran before arcy.init() resolved, most often a race between your auth state loading and the script tag executing. Call identify() from the same place your session data becomes available, after init() has been called at least once earlier on the page.

updateUser() before any identify() or identifyAnonymous() call is a no-op by design: there's no profile yet to update, so nothing is sent.

What's next

Quickstart: the full install walkthrough these fixes assume