Troubleshooting — Kunan Technology

The authoritative list of error codes is the error-code reference supplied by Kunan support. This appendix does something else: it maps the situations you actually meet on screen onto a cause and a fix.

1. “The button I need is not there”

This is almost always a permission, not a bug. Merak does not render a control you have no permission for — it does not disable it.

Work through this in order:

Do you hold the permission? Open /profile; the Permissions card lists everything your roles give you. Compare against Appendix A §3.
Does the record’s status allow it? Many actions have a status precondition — delete an application only when it is inactive, unlock only a locked account. See Appendix B.
Is the feature flagged off? Agentless and images are flag-gated. If a whole section is absent for everyone, the flag is off for your deployment.
Is it a cross-feature dependency? A whole card or filter field disappears when you lose the other resource’s read permission — the Devices card needs device:R, the organization filter needs organization:R, and so on.

2. Signing in

Symptom	Cause	What to do
”Invalid credentials”	Wrong email or password.	Re-enter; use Forgot password if needed.
”Account locked”	Repeated failed sign-ins.	An administrator unlocks it (Unlock on the account).
”Account disabled”	The account is deactivated.	An administrator re-activates it.
”Too many requests”	Rate limited.	Wait, then retry.
”Member accounts cannot access the console”	You used a member account in the Console.	Use the Agentless Portal.
Signed in, then immediately bounced out	The session could not be established, or the account type check failed.	Try again; if it repeats, check the audit log for the failure.
One “session expired” notice, back at sign-in	The refresh token aged out. Expected behaviour.	Sign in again.

2.1 MFA

Symptom	Cause	What to do
Code refused, prompt stays open	The code is wrong or was already used.	Wait for the next code — TOTP codes are single-use.
Enrollment dialog appears at sign-in	Policy requires MFA and this account never enrolled.	Scan the QR code and enter the code — 01 §4.2.
Asked for two codes (portal only)	Session and service grants each need one, and code reuse is disallowed.	Enter the next code, or Skip — 11 §2.3.
Lost the authenticator	—	An administrator uses Reset MFA on the account, then you enroll again.
Reset MFA button missing on an account	The account has not actually enrolled (MFA Enabled is OFF), or its status is not Active/Locked.	Nothing to reset.

2.2 Activation and password reset

Symptom	Cause	What to do
”Invalid link”	The token expired (one hour) or was used.	Ask an administrator to resend the mail.
”Already activated”	The account is active.	Sign in normally.
An older mail’s link stops working	Resending invalidates the previous token.	Use the newest mail.
The submit button will not enable	Not all six password rules are satisfied.	Read the live checklist under the field.
”Invalid input”	The submitted data was rejected.	Re-check and retry.

3. Creating and editing records

Symptom	Cause	What to do
”This name is already in use”	A record with that name exists (checked as you type).	Choose another.
”This email is already in use”	Another account uses it.	Choose another.
Next stays disabled on a create wizard	A required field is empty or invalid, or an async check is still running.	Wait for the check, then fix the field.
A field is red but shows no message	The message could not render.	Report it — this is a defect, not a rule.
A copied record cannot be created	The seed collided with something.	The numbering probes 20 times; beyond that the field’s own check flags it. Edit the name manually.
Access fields on a create form are read-only	You lack one of the both-side permissions.	See Appendix A §4.3. The record can still be created without that association.
A copied user came back with fewer roles	Anti-escalation dropped roles you cannot grant. A warning told you so.	Ask someone with those permissions to assign them.

4. Deleting

Symptom	Cause	What to do
Delete refused, “resource in use”	Linked resources still exist.	Members offer a force-delete confirmation. For applications, organizations, roles and users there is no force path — clear the dependency first.
No Delete button on an application	It is still active.	Deactivate first.
No Delete button on a role	It is a system role.	System roles cannot be deleted.
Batch delete says `M/N eligible`	Some rows fail the precondition (wrong status, or a system role).	Use Keep only eligible, or change the rows.
Delete on a member says devices remain	The member still has registered devices.	Deactivate then delete the devices, or use force delete.

5. Applications and endpoints

Symptom	Cause	What to do
”Virtual domain conflicts with X”, cannot submit	Another application intercepts the same address and port.	Change the address or the port. This one blocks on purpose — two applications intercepting one name cannot be told apart at DNS time.
A notice names another application under the service endpoint	The same backend target is already used elsewhere.	This does not block. One backend hosting many sites on one `IP:port` is a normal topology.
A collision message lingers after editing	It should not — both halves of a pair re-run the check.	Report it.
The collision check silently passes while the fabric is down	A failed check is treated as “no collision” and does not block you.	The backend validates again on submit.
Protocol type cannot be edited	It is fixed at creation.	The only exception is a record with neither protocol stored, which can be filled in once — and then it is fixed again.
Description cannot be edited	By design; it is read-only after creation.	—
A copied application’s virtual domain port is empty	Twenty probes upward found no free port.	Pick one yourself.

6. Agentless

Both layers must be in place: the member holds a seat, and the member is bound to the application. Plus the application itself must have agentless on.

Symptom	Cause	What to do
The Agentless switch on an application will not turn on	One of three gates: the L7 protocol is not `http`/`https`; the tenant’s agentless feature is not active; the agentless service quota is full.	Fix whichever applies. Turning it off is always allowed.
Alias conflict when enabling agentless	Another application derived the same alias.	Rename the application — the alias is derived and you cannot type it.
The Agentless Seat switch on a member is disabled	No seats are available, or none were purchased.	Free a seat, or purchase more. Check quota on `/profile`.
Turning a member’s seat off is refused	The member still holds agentless bindings.	Remove the bindings first; the message says how many remain.
Candidate rows in the agentless member picker are disabled	Those members have no seat.	Grant seats on the member records first.
A member sees a service card but cannot open it	The per-member binding is missing (common when access came only through an organization).	Bind the member individually.
A member’s service list is empty	No application access at all, or no reachable application has agentless on.	Check both.
A card is stuck on “preparing…”	The application’s agentless status is `provisioning` or `error`.	The backend re-drives provisioning; check the application detail.
A member’s access stops working after ~30 minutes	The service grant cannot currently be renewed.	Sign in to the portal again.
Seats were used up unexpectedly	Someone else took the last one between your check and your save.	The backend is the final authority on availability.

7. Merak Nodes

Symptom	Cause	What to do
No Download bootstrap kit button	The node is deployed. The installer deletes its single-use credential on success, so there is nothing left to hand out.	—
No Regenerate JWT button on a deployed node	Deliberately hidden, so re-issuing a credential cannot be used as a detour to a fresh installer.	—
The bootstrap kit dialog reports a load failure	The node is a cloud node, which has no installer.	Cloud nodes are provisioned for you.
The bootstrap kit says there is no valid token	The 24-hour enrollment token expired.	Use Regenerate JWT from the dialog.
`install.sh` refuses to run	The host is not Ubuntu 22.04 LTS.	Use a supported host.
Node creation fails with a quota message	The router quota is exhausted.	Check Merak Node quota on `/profile`.
Creation fails on step 1 with a field error	Duplicate name, malformed field, or router role not chosen (there is no default).	Choose a role explicitly.
A node reads `OFFLINE`	It is currently unreachable. This is not “deployed”.	Installer and JWT stay available. Check whether it ever enrolled before re-running `install.sh`.
Live status reads `UNKNOWN`	The routing layer could not be reached.	Check the fabric.

8. Import

Symptom	Cause	What to do
Submission blocked, “please split the file”	More than 500 rows.	Split it, or use Append import file across several smaller files — the 500-row cap still applies to the merged batch.
A relation cell shows a red tag	That name matched nothing. Relation columns are matched exactly — fuzzy matching is deliberately not used, so a near-miss cannot bind you to the wrong record.	Fix the spelling, or pick from the dropdown.
A permission name in a role import will not resolve	You do not hold that permission yourself, so it is not in your option list at all.	Ask someone who holds it, or drop the column.
An enum value will not resolve	Neither exact nor fuzzy matching found it.	Use the dropdown in the preview; the template’s examples are always valid values.
A status change is rejected as an error	The transition is not allowed by the lifecycle.	Import cannot bypass the lifecycle. See Appendix B §2.
A duplicate name is only an amber warning	Intentional — the backend allows two records with the same display name.	Nothing to fix unless you meant otherwise.
”Row N also updates this record”	Two rows matched the same existing record. The later submission wins.	Fine if they edit different columns; otherwise merge them.
A blank cell did not clear a field	Blank means “leave alone”, never “clear”.	Use `\N` where clearing is supported (descriptions).
A blank status or MFA cell did nothing	Those columns have no default in modify mode, deliberately.	Fill the cell explicitly if you meant to change it.
A modify row will not submit — “not matched”	No existing record was located.	Edit a matching key (ID, email, name); the autocomplete pins it when it resolves to exactly one.
A matched row keeps re-matching the wrong record	The pin is sticky by design.	Use Withdraw match, then edit a key. Matching is not re-run while withdrawn, so it cannot immediately re-pin what you just rejected.
A user import row failed but the user exists	A failed role assignment fails the whole user row.	Assign the roles manually, or fix and re-import.
A role import row succeeded but a permission is missing	Role import tolerates a failed permission grant — only a failed role creation fails the row.	Add the missing permission on the role detail page.
The second file replaced the first	It should not — appending merges.	Report it.
An appended file failed to parse	Only that file is lost.	Your existing rows are untouched; fix and append again.

9. Export

Symptom	Cause	What to do
A second tab says “queued”	Exports are serialised across tabs so the server is not asked twice.	Wait.
The relations column is missing from the CSV	You lack that relation’s read permission, so the column is omitted entirely.	See 09 §2.3.
Export selection lost the relations column	Selection export carries base columns only, because relations need a fetch per row.	Use the full export.
Chinese characters are garbled in Excel	Should not happen — exports are UTF-8 with a BOM.	Check that the file was not re-saved by something in between.
Progress sits at an indeterminate spinner	Normal until the first page returns.	Wait; it becomes `fetched / total`.
There is no Export button on Approvals	Approvals deliberately has none.	—

10. Lists, filters and tables

Symptom	Cause	What to do
Clicking a row body does nothing	Row-click selection only works after at least one checkbox is ticked, so rows cannot be selected by accident.	Tick a checkbox first, or double-click to open the detail.
My selection disappeared	A new search clears the selection. A background refresh does not.	Re-select.
The audit log seems to be missing read operations	The Action filter excludes `GET` when left empty, on purpose.	Tick GET explicitly.
A list opened already filtered	A saved default filter applied.	Clear default in the panel or in Preferences.
A shared link ignored my saved default	Correct — a URL that carries filters always wins.	—
A column I need is missing	Many columns are hidden by default.	Turn it on in the column settings gear.
Column settings did not follow me to another machine	They are stored per browser.	Export/import your preferences — 10 §9.
A timestamp looks wrong	Times follow your timezone preference.	Check `/preference`.
Times did not change after switching timezone	It applies from the next repaint.	Change page or reload.

11. Profile, tenant and quota

Symptom	Cause	What to do
The tenant name is blank in the header	Reading it needs `tenant:R`; the page degrades rather than failing.	Assign a role that carries it.
”This account cannot retrieve quota information”	Reading quota needs `license:R`.	Same.
The quota card shows a spinner forever	It should not — a spinner means “still loading”, the message means “loaded, nothing there”.	Report it.
A quota shows `0` as the limit	`0` means unlimited for every resource except agentless seats, where it means not purchased.	Read the label, not the number.
Changing my password signed me out	Expected. You must sign in again with the new password.	—
Importing preferences changed my language	Language counts as default when it equals that device’s browser language, so it is omitted from exports.	Set it manually — 10 §9.
Importing `{}` reset everything	Expected. Import is an authoritative replace; absent dimensions reset to default.	—

12. Approvals

Symptom	Cause	What to do
I see the queue but no decision buttons	You hold `tokenRequest:R` but not `tokenRequest:U`.	Ask for the update permission.
Decision buttons missing on some rows	Only `PENDING` rows can be decided.	—
The resource dialog says the payload is too large	Over 20,000 characters; it is not dumped raw, on purpose.	Investigate the requester.
A nested branch says it is too deep	Deeper than 8 levels.	Same.
The dialog content failed to render	Only the dialog breaks; the list stays usable and the next row starts clean.	Report the payload shape.
A device payload looks trustworthy	Every field in it is asserted by the client and can be forged. There is deliberately no “verified” badge.	Reconcile against your asset inventory, directory or MDM.
Only a fingerprint hash is meaningful to me	The fingerprint source is always shown beside it.	A hardware-derived fingerprint is far stronger than one derived from a MAC list.

13. Error code prefixes

Full details are in the error-code reference supplied by Kunan support.

Prefix	Area
`COMMON_`	Permission, not found, rate limit, server error
`AUTH_`	Sign-in, session, MFA, account activation, auth server
`USER_`	Administrator management
`MEMBER_`	Member management
`DEVICE_`	Device management and enrollment
`APP_`	Application management
`NODE_`	Merak node management
`ROLE_`	Role management
`PERM_`	Permission management
`ORG_`	Organization management
`WORKFLOW_`	Access request workflow
`AUDIT_`	Auditing
`TENANT_`	Tenant management
`LICENSE_`	Licensing
`AGENTLESS_`	Agentless seats, bindings and provisioning
`AGENT_`	Agent platform (Agent client contract, not the Console)
`CONN_`	Connection management (Agent client contract)

Account activation no longer has its own prefix. The codes for a spent activation link and a rejected password are AUTH_024 and AUTH_025; see §6 for agentless symptoms, and the error-code reference for what each code means and what the interface does with it.
If you are quoted a code the catalogue does not list, quote it verbatim when escalating — the interface shows a generic message for anything it does not recognise, so the code is the only detail that survives.

14. When to escalate

Collect these before raising a ticket — the first three are usually enough to find the event in the audit log:

When it happened, and your timezone setting.
Your account and the record involved.
The Request ID from the audit log entry, if you can find it.
The exact message shown on screen, and the error code if one was given.
Whether it reproduces, and whether it happens for other administrators.