When the local environment fails
Find the sentence that matches what you can see. Each entry has the same five parts: what you see, likely causes, how to tell them apart, what to change, and how you know it is fixed. Stop when the check passes. If you have never had a seeded record on the screen, start with Set up a local NRTR environment.
The client says connection refused
What you see. The client opens. Requests fail immediately. The message says the connection was refused, not that you are unauthorized.
Likely causes. The Python service is not running. The client port does not match the service port. Another process owns the port and is not the service.
Tell them apart. From a terminal, request the health address you wrote down during setup. If the terminal is also refused, the service is down or the port is wrong. If the terminal succeeds, only the client is pointed at the wrong place.
Change. Start the service if the terminal failed. If the port is taken, stop the other process or move the service and the client together. Never move only one of them.
Fixed when. The health address succeeds in the terminal, and the client shows the seeded record.
The client opens and every list is empty
What you see. No error. Lists render with zero rows.
Likely causes. Migrations ran and the seed did not. The client and the SQL prompt are looking at different databases.
Tell them apart. Count rows with the database address in the service’s environment file. Then call the service’s list route.
Change. Point the service, the SQL prompt, and the client at one address. Load the seed. Do not create a second database to “try again” until you know which one the service uses.
Fixed when. The SQL count, the list route, and the client all show the same row.
Authenticated calls return 401 on your own machine
What you see. The health check succeeds. Calls that need a token return 401 and error.code of unauthorized.
Likely causes. The token is expired. The environment still has a signing secret from a hosted setup. The client is sending a vendor key instead of the local bearer token.
Tell them apart. unauthorized is this entry. validation_failed is the next kind of problem, not this one. Read the code before you change JSON.
Change. Issue a new local token. Remove hosted secrets from the local environment file. Restart the service so it reads the file you edited.
Fixed when. The create call in Record a health observation returns 201.
A create returns 400
What you see. Status 400, error.code of validation_failed, and error.fields naming one or more fields.
Likely causes. The value was sent as a string. The unit is not allowed for the code. The time has no offset. The body includes profile_id.
Tell them apart. The name in error.fields is the field. The reason is the rule. Do not infer a different field.
Change. Fix the named fields. Send the body again. Do not retry the original body.
Fixed when. Status is 201 and the read-back matches value, unit, and time.
The Flutter analyzer fails on a clean checkout
What you see. Missing types for generated classes. flutter pub get already succeeded.
Likely causes. Generated files are not in Git, and the generator has not been run here.
Tell them apart. The missing path is a generated output, not a file a person wrote. If a person wrote it, this entry is the wrong one. Ask before you regenerate over a hand-written file.
Change. Run the generator named in the README. Do not hand-write the classes.
Fixed when. flutter analyze reports no errors in those files, and the client starts.
Records save, and suggestions never return
What you see. Creates return 201. The suggestion call spins or fails. Screens that do not need a suggestion still work.
Likely causes. The model process is not running. A flag still requires it for a task that does not need it.
Tell them apart. Hit the model process’s own health check. Read the flag in the environment file.
Change. Start the model process, or turn the flag off for a user-interface task. Do not put a stand-in suggestion in the client. An empty suggestion must look empty.
Fixed when. Either a real suggestion returns, or the screen says suggestions are off and the rest of the record still loads.
The service prints a bind error and exits
What you see. The process starts, reports that it cannot bind, and stops.
Likely causes. A previous run is still listening. You started it twice.
Tell them apart. Find the listener on that port. If it is your previous service, you do not need a new one.
Change. Stop the old process. Start once. Confirm a single listener.
Fixed when. The health check succeeds, and a second start fails because the port is taken by the one you meant to keep.
The client fails with no message
What you see. A blank region where a record or an error should be.
Likely causes. The client treated a failed request as an empty list. This is a defect if the service actually returned an error.
Tell them apart. Watch the service log while you reload. An error in the log plus silence in the client means the client swallowed it. Silence in both means the client never called.
Change. If it never called, fix the base address. If the service logged an error, file that as a client defect with the status and error.code. Do not paper over it with seed data.
Fixed when. A forced failure, such as stopping the service, produces a visible error, and starting it again restores the seeded record.
When to stop using this page
If you have worked two entries and the verification for the second one failed in a new way, you are no longer in a known setup fault. Write down the last command, the status code, and error.code if there is one. Bring that, not a theory, to the person who owns the service.