Troubleshooting

The problems below are ordered roughly by when people hit them. Each one gives the situation, what the message actually means, and the command that resolves it.

Before anything works

You have not signed in yet

Hosted commands — nexa repos, nexa publish, nexa link, nexa sync inside a hosted context, nexa logout and a hosted nexa get — need an authorized account. Run one before signing in and it stops immediately, reporting that this machine is not signed in to Rinko Hub with that profile.

The fix is to authorize this machine, which opens a browser:

$ nexa login

A closely related message says this profile is not signed in to Rinko Hub: the profile exists on this machine but holds no current session, for example after nexa logout. Both are resolved by nexa login. A third variant asks you to sign in again because an existing session predates the current CLI and is not bound to an origin; the fix is the same command.

Where you are standing

You are not inside a repository

Commands that act on a repository — nexa status, nexa record, nexa history — search the current directory and then its parents. When none of them contains a repository, the command reports that no repository was found at or above the directory you are in, and names that directory:

$ nexa status

error: no repository found at or above: ~/Desktop

There are three ways out, depending on what you meant to do:

• You meant to work in existing work. cd into the working context directory first. Contexts live beneath your Development Root, one directory each.
• You meant to start something new. nexa init creates a repository in the current directory.
• You meant to bring work in. nexa get <owner>/<repo> materialises a working context under your root.

The command needs your Development Root

nexa contexts, nexa get, nexa drop, nexa goto and nexa disconnect operate on the Development Root rather than on a repository. Running one outside any root is refused, and the message says so: in a folder with no Nexa state it reports that there is no Development Root here or in any folder above it, and to create one with nexa root.

If you have not declared a root yet, declare one. It adopts the current directory and moves nothing:

$ nexa root

If you already have one, you are probably outside it. cd into your Development Root, or any project inside it, and run the command again.

Privacy and .nexapolicy

"labels are repository-specific"

Your Development Root's .nexapolicy names a label inside global. A label belongs to one project's repository, so a rule naming it must sit in that project's block; in global it would reach every project and be resolved against each one's own, unrelated labels. check, validate, explain and record all refuse it, and nothing is recorded. The message names the block to use. Move the rule into project "my-project" { … } — once for each project that should have it, creating the label there first with nexa <project> label create <key> if it has none — and run nexa <project> policy validate.

"names an exact path with no file; nothing was recorded"

A rule names one exact file that is not in the project, so it would protect nothing. Usually it is a typo — .app.json for app.json — or an example path the project does not have. nexa <project> policy explain <path> shows what a path resolves to; correct the path, or remove the rule, and record again. A pattern such as secrets/** or **/*.pem that matches nothing yet is only a warning.

A file you labelled is readable on Rinko Hub

Labels are not retroactive. If the file was recorded before its rule existed, that version holds it readable, and publishing or syncing uploads that version. Labelling it now seals it only in the versions recorded from now on. Treat what it held as exposed: rotate the credential, check the rule with nexa <project> policy explain <path>, and record again. The first nexa publish of a project warns about exactly this case — a protected file that an earlier version holds readable — before it uploads anything.

Protect private files before hosting is the order that avoids it.

Publishing

nexa publish refuses: no recorded version

nexa publish publishes the version you have recorded. Run it in a repository with no version yet and it refuses rather than creating an empty hosted repository, with the message No recorded version to publish. Run nexa record -m "Initial version" first.

Do exactly that, then publish again:

$ nexa record -p my-project -m "Initial version"

$ nexa publish -p my-project

Published to Rinko Hub.

Run from inside the project directory instead of the Development Root, the -p my-project can be left out.

The related case is a repository that has a recorded version but also has edits since. publish succeeds, publishes the recorded version, and prints Warning: unrecorded working-tree changes were not included. so you know the edits did not go. Record them and run nexa sync -p my-project.

Rinko Hub is still preparing the repository

Creating a hosted repository takes Rinko Hub a moment — typically seconds, occasionally up to about two minutes — and nexa publish waits for it before synchronizing. If the wait runs out, the command stops with Rinko Hub is still preparing this repository. Run nexa publish again in a moment; nothing needs to be recreated.

That message means what it says. The repository was created and is being prepared; nothing failed and nothing is half-made. Wait a little and run the same command again:

$ nexa publish

Published to Rinko Hub.

A second publish in the same directory never creates a second repository. It finds the one it already created and finishes the synchronization it was waiting to do. Do not delete anything on Rinko Hub, and do not rename the directory in between.

"Repository redundancy is temporarily degraded"

Rinko Hub keeps more than one copy of each repository, and publish and sync synchronize with all of them. When one copy is temporarily unreachable, the command still succeeds — your work reached Rinko Hub — and adds one line on standard error: Repository redundancy is temporarily degraded; Rinko Hub will retry.

Nothing is required from you. Rinko Hub brings the copies back into step itself once the copy is reachable again; you do not re-run sync to repair it, and your next ordinary sync is not affected. The line is information about Rinko Hub's own redundancy, not about your repository's integrity. If you want to see which copy is behind, set NEXA_DIAGNOSTICS=1 when running the command to print per-copy detail; nexa repo route shows how the repository is routed. Neither is needed for ordinary work.

The repository is on Rinko Hub but shows no code

After a successful nexa publish this should not happen: the command does not print Published to Rinko Hub. until the recorded version has been synchronized, and Rinko Hub serves the same content from every web origin. If you are looking at an empty repository, check in this order:

• Did publish finish? If it stopped with the still-preparing message above, the repository exists but the synchronization has not happened yet. Run nexa publish again.
• Was anything recorded? publish refuses when nothing is, so an empty repository is not the result of publishing an unrecorded tree — but a version recorded from an empty directory is genuinely empty. nexa history shows what you recorded.
• Are you looking at the right repository? nexa repos lists what your account can reach, with each repository's owner and name. A publish under --org puts the repository under that organization, not your personal account.
• Are your edits recorded? Files you changed after your last nexa record are not on Rinko Hub yet. Record them and nexa sync -p <project>.

If all four check out and the repository is still empty, that is a defect rather than a step you missed; running the command again with NEXA_DIAGNOSTICS=1 shows per-copy detail to include in a report.

Refusals, and commands that do not exist

nexa drop refuses: unrecorded changes

Dropping a working context deletes its directory. If that directory contains edits you have not recorded, nexa drop refuses and exits 1 rather than destroying them. The message states the condition and offers both ways forward: record the changes, or discard them explicitly.

To keep the work, record it first, then drop:

$ nexa record -m "Work in progress"

To discard it deliberately, say so:

$ nexa drop demo --force

Removed demo from this Development Root.
The repository, its history and its workspaces were not touched.

That second line is true in both cases. Dropping a context is a local operation: the repository, every version in it, and every other context of it are untouched. What --force discards is only the unrecorded edits in that one directory.

You typed nexa clone

nexa clone does not exist. It is not an alias and there is no compatibility shim — the top-level command was removed outright, so typing it produces an unrecognized-subcommand error:

$ nexa clone acme/demo

error: unrecognized subcommand 'clone'

The error is followed by a list of similar-looking subcommands and the general usage line. Ignore the suggestions: the command you want is nexa get, which brings a repository into your Development Root as a working context.

$ nexa get acme/demo

You are looking for nexa add or nexa commit

Neither exists, and neither ever did. Both produce an unrecognized-subcommand error:

$ nexa add file.txt

error: unrecognized subcommand 'add'

The reason is structural rather than a missing feature: there is no staging area and no index, so there is nothing for add to do. A version is a whole tree rather than a delta, which means the working tree already is the staging area.

Record the whole working tree:

$ nexa record -m "First version"

Created version 40f877ccd802
  workspace: main
  files:     1

Selected on branch main.

Or name paths to record only part of it:

$ nexa record -m "Tidy the parser" src/

The noun is version, never commit. For why the two are different objects rather than two words for one, see repositories and versions. For the other Git verbs that do not exist here — rebase, stash, reset, blame, clean — the CLI reference lists each with what to use instead.

nexa status says there is nothing to record

In a repository with no versions yet and no files, nexa status reports that the working tree is empty. This is not an error — there is genuinely nothing to record until you create a file.

Once a file exists, the same command reports it as untracked and tells you how to record it:

$ nexa status

On branch main
No version yet.

1 untracked file(s). Record them with:
    nexa record -m "<message>"

Sync succeeds but contributes nothing

If your account has read access to a repository but not write access, nexa sync succeeds and reports that nothing was contributed. It is not refused, and the exit status is zero.

This is the intended behaviour rather than a problem to fix: reading is what read access is for. If you expected to contribute work, you need write access to that repository — ask whoever administers it on Rinko Hub. Attempting to push explicitly, on the advanced peer-to-peer surface, is what produces an outright refusal naming the access level.