Troubleshooting, from the words the platform actually prints.

Run every command on this page from the installation directory.

What you will achieve

Find the message you saw in the tables below. Each row gives its cause and the next action. The tables group messages by the action you were attempting.

What it is for

A refusal in the customer profileDeployment profileA setting that selects customer or development behaviour. Customer mode refuses development credentials and uses the signed-in session as the identity. is deliberate. The platform refuses unsafe settings, undeclared network access and identities it cannot verify. Read the full message and find its row below. It names the setting to change.

Installation diagnostics

Run ./lens doctor from the installation directory. It checks the host first, then the running installation. Each failed check names what it found and the command that repairs it. Deployment runs the same installation checks before showing sign-in details.

If a required service is stopped, run ./lens start before repeating ./lens doctor. An installation without a model server can still import data and browse the twinTwinNovusLens’s model of one organisation, built from records about its teams, services and how they rely on one another. It is only as current as those records..

Read the analysis status

./lens status reports setup progress and containersContainerA running program with its own packaged software and isolated environment, managed by Docker on the host.. To inspect analysis stages, query the reasoning service inside its container:

./lens exec -- python - <<'PYTHON'
import http.client
connection = http.client.HTTPConnection("127.0.0.1", 8500, timeout=10)
connection.request("GET", "/ready")
response = connection.getresponse()
print(response.status)
print(response.read().decode())
PYTHON

The response lists organisation errors and failed stages. ready means the current checks passed. degraded means a recent analysis stage failed. failed means records cannot advance. stale means the recorded projectionProjectionThe regular pass that brings the read model up to date with the canonical log. It runs every 30 seconds by default. pass is too old.

If a stage failed, collect its name and error below. Send them to your demo provider before presenting the affected analysis.

If the reasoning container is unavailable, collect the container list and logs below instead.

Reset the initial operator passphrase

If sign-in rejects the recorded credentials, check the login name first. For this demo, it is demo-owner unless you chose another name.

If you need to reset it, use the command below. This example preserves the initial operator’s global role and organisation scope. Use it only for that initial operator.

Replace demo-owner with your initial operator login. Run the command from the installation directory. Enter a new passphrase at the hidden prompt:

./lens exec -- python -c '
import getpass, subprocess, sys
phrase = getpass.getpass("New operator passphrase (12+ characters): ")
if len(phrase) < 12:
    raise SystemExit("Use at least 12 characters.")
subprocess.run([
    sys.executable, "-m", "conway_graph", "viewer",
    "--viewer", "demo-owner", "--role", "operator", "--org", "*",
    "--passphrase", phrase,
], check=True)
'

Save the new passphrase in your password manager. Sign in again with the same login name. If sign-in reports too many attempts, wait ten minutes before retrying.

For another account, follow Accounts and stewardship with its existing role and organisation scope.

Collect a diagnostic packet

Create a private directory for the command output:

umask 077
mkdir -p demo-diagnostics
./lens version > demo-diagnostics/revision.txt
./lens doctor > demo-diagnostics/compose-version.txt
./lens status > demo-diagnostics/setup-status.txt 2>&1
./lens compose -- ps -a > demo-diagnostics/containers.txt
./lens compose -- logs --no-color --tail 100 > demo-diagnostics/services.log 2>&1

If a command fails, retain its output and continue with the next diagnostic command.

Record the failed setup step, exact error message, image release and whether the failure followed a restart or configuration change. For a missing journalInstallation journalA saved record of setup steps, their attempts and whether they started, completed or failed. It records progress, not a backup of application data., record which file or volume is missing. Keep the original journals and configuration untouched.

Review the packet for credentials and organisation data. Remove those values before sharing it. Keep .novuslens.env, passphrases and registry tokens private.

Send the redacted packet to the person who provided the demo. Alternatively, report the fault through the repository issues  if you have access. Ask that maintainer to assess the preserved state.

Choose the next action

The installer has no automatic journal repair command. To recover from a backup, the installation operator runs ./lens restore. Otherwise ask your installation operator or demo provider for approved recovery instructions for the preserved installation. Without those instructions, retain the original state and wait for maintainer assessment.

Configuration refusals

Each ./lens command checks .novuslens.env before it runs Compose, and names the line it refuses. Configuration lists each refusal with its fix. The secret rules are in Secrets. The profile rules behind them are in The customer profile.

Deployment failures

./lens start names the step that failed and the command’s own output. Correct the cause, then run ./lens resume.

Sign-in

Sign-in is the only identity the customer profile accepts. These are the messages on the sign-in page and at the proxy.

Readiness and health

./lens monitor shows each service’s health check and the age of the read modelRead modelThe database tables used by the map, Ask and Find. NovusLens rebuilds these tables from its history of recorded changes. for each organisation. Starting, stopping and health explains /health, /ready and their states.

If readiness is degraded or failed, read the errors with Read the analysis status. Then check that the database, mesh and model server answer. Retry quarantinedQuarantineA holding area for a log entry that could not be applied. The entry keeps its error and waits for a retry or an operator. items for one organisation:

./lens graph retry --org <org>

To retry one item, name its log position:

./lens graph requeue --org <org> --hlc <position> --host mesh-0

Both actions are audited.

Backup and restore

Backup and restore lists the backup and restore messages, with the action for each. Restore replaces the database and all four state volumes. Add --yes to confirm. stops a restore before it starts. It changes nothing.

Refused record changes

These come from the reasoning service and carry the role rule in their text.

Notifications not arriving

Each delivery is retried up to eight times in total, with the waits given in Accounts and stewardship. List the most recent deliveries to see what was issued and its outcome. Use the operator login chosen during setup:

./lens connectors notify deliveries --org <org> --viewer <operator-login> --limit 20

The platform refuses a destination that breaks any of these rules, with one of these messages:

• Endpoint may not be a cloud metadata service, and Endpoint may not be a link-local address. The platform never sends to these.
• A loopback receiver needs NOVUSLENS_ALLOW_LOOPBACK_WEBHOOK=1 in the deployment. Inside the installation, a loopbackLoopbackA network address that refers to the same host, such as 127.0.0.1. Other hosts cannot reach a service through that address. address is the service’s own container. Use the receiver’s network address instead.

Forgetting an organisation

Erasure cannot be undone. Add --yes to confirm. means ./lens forget-org was run without --yes. It deletes data, so the flag is required. A forgotten organisation is marked, and the materialiserMaterialiserThe component that reads recorded changes in order and updates the database. It records its place so it can continue after a restart. refuses to rebuild it: organisation <org> is marked forgotten (F7): nothing rebuilds it from the log.

When the cause is not in this list

Do not work around a refusal by editing the code, turning off a check, or copying a value from another installation. Collect the message in full and the diagnostic packet, and send them to Novus. Do not send a secret value; describe the variable name instead.