Diagnosis and log reference

This section explains how to identify the cause and take first-line action when the Arm AI Model Optimizer SDK (np) behaves abnormally. For any issues you cannot resolve, follow the Reporting an issue procedure.

Diagnosis flow

When you notice abnormal behavior, diagnose in the following order. If a step does not resolve the issue, move to the next one. If you cannot fix it yourself, report it to support.

Symptom checklist

Symptom	Likely cause	First-line action	Reference
Pipeline stops midway (SIGKILL / abnormal exit)	Out of memory (system RAM or GPU)	Lower batch_size in run.detail.yaml (detail.batch_size, applies to AQ, GQ, and evaluate), then np run --retry	run.detail.yaml
Run fails when the host disk is full	No free space in the execution environment	Free up disk space, then np run --retry (NP-SIO-500)	Error Codes
GPU unavailable (No CUDA GPUs are available, NP-SSM-503)	No GPU worker capacity on the server side	Retry. If the issue persists, ask your operator to check GPU scheduling	Error Codes
Exits with a [NP-S**-***] error code	Varies by code	Look up the error code reference	Error Codes
API connection failure	Server-side or network issue	Respond according to the error code (NP-SAP-xxx)	Error Codes
Accuracy noticeably lower than expected	Optimization configuration or calibration	Review the run.yaml config and calibration dataset	run.yaml
MLIA profiling missing latency and memory columns	Backend is xnnpack: MLIA only produces MACs and parameters there	Expected. Full latency and memory from MLIA is available only when targeting ethos_u	Profiler
np run --wait stopped printing after Ctrl+C, but the run is still listed as active	Ctrl+C only detaches the CLI; it does not cancel the run	Expected. Check with np status. Use np cancel if you actually want to stop it	Job States

Job states

Because np run submits work to the backend for asynchronous execution, a job moves through these states:

State	Meaning
pending	Queued, waiting for a worker
running	Executing on a GPU worker
success / failed	Finished
canceled	Cancellation requested with np cancel (a running job finishes its current step before cancellation takes effect)

Exit codes

When the CLI exits with a non-zero status, the exit code narrows down the failure category (useful for scripting and CI branching).

Exit code	Meaning
0	Success
1	General error (including backend errors; see the message for details)
2	Invalid arguments or usage
3	Configuration or environment error (for example, missing environment variable)
4	Backend connection failure or timeout
5	Validation failed (np validate itself reports invalid)
130	Interrupted by user (Ctrl+C)

Common issues

See also Client error codes.

Symptom	Cause	Fix
Environment variable NP_CLIENT_API_URL ... is not set	Connection info not configured	Set export NP_CLIENT_API_URL=... and retry
Not authenticated	Not logged in, or session expired and refresh failed	Run np auth login <token>. To obtain or replace a token, see Manage access tokens
Failed to connect to the backend	Network issue or wrong URL	Check connectivity with np health ready. Verify the URL
The backend request timed out	Backend is slow to respond	Retry shortly. Contact your administrator if the issue persists
Workspace not initialized	Command run outside an initialized workspace	cd into the workspace root, then run np workspace init
Workspace already exists	Re-initializing an already-initialized directory	Use a different directory, or keep using the existing workspace
Invalid workspace config	Local configuration file corrupted	Delete ~/.config/np/config.json and re-run np workspace init
No backend project ref registered for this path	Command run outside a project folder, or the ref was lost	Run from the folder created by np projects create, or pass --project <ref_id>
Unsupported device combination	Unsupported device/runtime/backend combination	Check supported combinations with np devices ls
not a pre-approved model card on model registration	Model isn't on the allow-list	Check allowed model cards with np models register --help
Experiment/project name format error (422)	Name violates naming rules	Use letters, numbers, hyphens, underscores; 1–50 chars
Timeout during np evaluate --wait	Evaluation is still running on the server	Check progress with np status, or re-run np evaluate ... --wait
No results from np analyze sensitivity (404)	Sensitivity cache not yet generated	Run np run or np evaluate with the relevant metric enabled first

If you still cannot resolve your issue, contact support for Arm AI Model Optimizer with the console output.

Client error codes (NP-C{module}-{status})

Errors surfaced directly by the np thin client use the form NP-C{module}-{HTTP-status-like number}. This is distinct from the pipeline-internal NP-S{module}-{status} codes below, which originate from the backend's own processing of a submitted job.

Code	Meaning	Action
NP-CAP-400/404/409/422	Invalid request, resource not found or conflict, validation failed	Re-check the command arguments and target ID
NP-CAP-401/403	Authentication required or permission denied	Run np auth login <credential>, or contact your administrator
NP-CAP-500/502	Backend internal error	Contact your administrator if the issue persists
NP-CAP-503	Failed to connect to the backend	Check NP_CLIENT_API_URL and network connectivity
NP-CAP-504	Backend request timed out	Retry shortly
NP-CVA-422	Unsupported device combination	Check with np devices ls
NP-CMD-400	Model not on the allow-list	See np models register --help
NP-CWS-404/409/422	Workspace not initialized, already exists, configuration corrupted	Run np workspace init, use a different directory, or delete ~/.config/np/config.json and re-initialize
NP-CPR-404/409/422	Project ref missing, already exists, invalid name	Run from the project folder, or check naming rules
NP-CXP-409/422	Experiment state conflict or invalid name	Use np run --retry, or check naming rules
NP-CRP-404 / NP-CST-404 / NP-CCL-404	No ref registered for report, status, or cancel target	Run from the project or experiment folder, or pass --experiment/--project
NP-CEV-404/422	Evaluation target missing or invalid metric argument	Check the target ID. Use -m NAME[:key=value] format
NP-CEV-504	Timed out waiting on evaluation (still running server-side)	Check with np status
NP-CEX-404 / NP-CPF-404	No ref for export or profile target	Run from the experiment folder, or pass --experiment
NP-CAN-404	No sensitivity cache found	Run np run or np evaluate with the metric enabled first
NP-CCF-500	Client configuration error	Check the required environment variable is set
NP-CX-999	Unexpected internal error	Contact support with logs if it recurs

Pipeline error code reference

Code format

Error codes use the form NP-S<module>-<status>: S is the SDK service, the next two letters identify the module, and the number mirrors an HTTP status (4xx = input or client issue, 5xx = server or runtime issue).

e.g. NP-SWS-404 = SDK, then WS (Workspace), then 404 (Not found)

Prefix	Module	Prefix	Module
SAP	API client	SRN	Run (pipeline)
SCF	Configuration	SSM	Scenario Manager
SDS	Dataset	SVA	Validator
SIO	File I/O	SWS	Workspace
SML	Model	SXP	Experiment
SPR	Project	X	Meta (uncategorized)
SRM	Result Manager

On error, the CLI prints the code together with a cause and action hint. The tables below are a summary. The most accurate guidance is the CLI output message.

Who resolves it

Responder	Handles
You (SDK user)	Configuration, input, and context errors: fix the command and re-run
Your system administrator	Host-level issues on the on-premise machine: server, network, disk, GPU, and credentials
Support for Arm AI Model Optimizer	Software internals and unexpected failures: report the issue

Errors you can fix yourself

Configuration, input, and context errors, usually resolved by correcting the command and re-running.

Code	Meaning	Action
NP-SCF-400	Invalid YAML syntax	Check the YAML syntax of run.yaml
NP-SCF-422	Invalid configuration	Validate run.yaml against the schema. Use --steps with go,gq or aq,go,gq, and check required fields (-C and -E)
NP-SCF-500	Configuration load failed	Verify run.yaml exists and is valid
NP-SDS-404	Dataset not found	Run np datasets ls to see registered datasets
NP-SDS-409	Dataset selection conflict	Resolve name duplication or ambiguity
NP-SDS-422	Invalid dataset	Use a dataset matching the task, and check the format
NP-SML-404	Model not found	Run np models ls to check the ref_id
NP-SML-409	Ambiguous model selection	Specify the type with --as model|job|experiment
NP-SML-422	Unsupported model format	Only .pt2 models are supported, so re-create the model
NP-SPR-404	Not inside a project	Move into a project directory or np projects create
NP-SPR-409	Project state conflict	Rename, or run at the project root
NP-SPR-422	Invalid project input	Check naming rules (only alphanumeric characters, -, and _, 3–50 characters, must start with a letter or number)
NP-SWS-404	Workspace is not found or is outside workspace	np workspace init or move into the workspace directory
NP-SWS-409	Workspace state conflict	Check for existing workspace or run at root
NP-SWS-422	Invalid workspace configuration	Check workspace configuration
NP-SXP-404	Experiment resource not found	Run np experiments ls, move into an experiment directory
NP-SXP-409	Experiment state conflict	Resume with np run --retry or create a new experiment
NP-SXP-422	Invalid experiment name	Check naming rules
NP-SXP-429	Experiment limit exceeded	Clean up unneeded experiments
NP-SVA-422	Invalid validation input	Check supported device, runtime, and quantization scheme combinations
NP-SSM-400	Scenario YAML parse error	Check the scenario YAML syntax
NP-SSM-404	Scenario resource not found	Check the scenario YAML and detail paths
NP-SSM-409	Duplicate step combination	Remove the duplicate step combination
NP-SSM-422	Invalid scenario	Check the schema, step type, hardware, and metric
NP-SIO-403	Permission denied	Check directory permissions
NP-SIO-404	Path not found	Check the workspace structure and file path
NP-SIO-409	File already exists	Clean up the target path
NP-SRN-998	Pipeline canceled	You (or someone with access) ran np cancel on this experiment. Re-run when ready (this is not an error)

Errors for your system administrator

Host-level issues on the on-premise machine. If the administrator cannot resolve them, report to support.

Code	Meaning	First-line action
NP-SAP-401	Authentication required	The SDK could not authenticate to the backend: check the credentials set at install (.env or license-gate)
NP-SAP-404	Remote resource not found	Check storage and server status
NP-SAP-502	Backend or API error	Check the API server status
NP-SAP-503	API connection failed	Verify the API server is running and NP_ENTERPRISE_API_URL is correct
NP-SAP-504	API timeout	Retry, then check whether the server is responsive
NP-SIO-500	File system error	Check disk space and path permissions on the host
NP-SSM-503	GPU unavailable	A server-side capacity issue. Report it to your operator with the error code and the time of occurrence

Errors to report to support for Arm AI Model Optimizer

Software internals and unexpected failures. Report the issue with the logs attached.

Code	Meaning	First-line action
NP-SVA-404	Validation resource or device not found	Run np devices ls to see the devices configured at delivery. If the one you need is missing, report it
NP-SRM-500	Catalog load failed	Re-run. If the issue persists, report
NP-SRN-500	Pipeline stage failed (optimize, profile, evaluate, export, and so on)	Check the logs for the underlying cause (often a fixable configuration or model issue). If none is found or the issue repeats, report
NP-SSM-500	Scenario internal error	Check disk and permissions, then report
NP-X-999	Unhandled exception	Report (attach logs)

Log reference

Log locations

• Console output: errors and hints are printed during execution as [NP-S**-***] <message>.
• Log files: each run is logged automatically to the logs/ folder of the experiment. You do not need to capture the console manually.

<workspace>/<project>/<experiment>/
├── run.yaml          # pipeline configuration
├── run.detail.yaml   # fine-grained overrides (optional)
├── meta.json
├── report.json       # raw np report output
├── logs/             # execution logs (written automatically)
└── NN_<step>/        # e.g. 01_graph_optimize, 02_graph_quantize
    ├── job.json
    └── artifacts/

Log levels

Each log line is tagged with a level:

Level	Meaning
DEBUG	Verbose diagnostic detail
INFO	Normal progress
WARN	Attention needed, but the run continues
ERROR	A failure occurred
DONE	A step or the pipeline finished successfully

Collecting logs to report

When reporting an issue, attach the files that already exist in the affected experiment directory:

• the logs/ folder of the experiment
• run.yaml (and run.detail.yaml if used)
• the meta.json, report.json, and job.json for the failed step

Next steps

If you cannot diagnose and resolve issues yourself, follow the procedure in Reporting an Issue.