Is this page helpful?

Troubleshooting NIM Metadata API#

The following issues might arise when you work with the NIM Metadata API. Branch on the HTTP status code and on requestStatus.statusCode rather than on the description text, because the description is written for people and changes over time.

A 400 Status Code with INVALID_REQUEST#

Symptom: A metadata request returns HTTP 400 with requestStatus.statusCode set to INVALID_REQUEST.

Cause: A request parameter is missing or malformed, or stored metadata failed validation on read.

Solution: Check the parameters against the following table. Use the response description for diagnosis rather than programmatic branching.

Parameter or Condition	Check or Resolution
`resourceId`	Use two or three nonempty path segments and the correct organization. Pass `nim/meta/llama-3.1-8b-instruct` rather than `nim/meta/llama-3.1-8b-instruct:2.0.12`. Pass the tag separately. Empty segments such as `nim//model` and `nim/model/` are rejected. The organization is matched without regard to case.
Missing `resourceId` or `tag`	Supply both parameters in the query-parameter form.
`team`, `name`, or `tag`	Remove embedded slashes or colons from individual path segments.
Artifact or payload validation	Report the service-side data problem with `requestStatus.requestId` rather than retrying with different parameters.

For the accepted request forms, refer to Endpoints.

A 404 Status Code for a NIM Microservice That Exists#

Symptom: A catalog-listed NIM microservice returns HTTP 404 from a metadata endpoint.

Cause: Metadata is unavailable for the requested tag, or the request uses a path form that does not match the repository layout.

Solution: Complete the following checks in order:

Confirm the exact container tag.

Metadata is stored per tag, so metadata for 1.2.0 says nothing about 1.2.1.
Confirm whether the repository belongs to a team.

If nim/{repo} fails for a team-owned NIM microservice, use nim/{team}/{repo}.
Check metadata coverage and publication timing.

NIM microservices published before the API launched in September 2026 generally have no metadata until republished. Metadata can also lag a new container release. If polling after a release, bound the attempts and use backoff as described in Notes for Automated Agents.

A 404 status code answers whether metadata is available for that tag, rather than whether the NIM microservice exists. If no metadata is available, use the microservice’s documentation and support matrix.

A 500 Status Code for One Specific NIM Microservice#

Symptom: One NIM microservice consistently returns HTTP 500 while metadata requests for other microservices succeed.

Cause: The stored metadata is likely unreadable.

Solution: Report the service-side fault with requestStatus.requestId, resourceId, and the tag. Retrying the same stored-data fault does not help. For the response envelope, refer to Endpoints.

A Profile Matches on gpu but Not gpu_device#

Symptom: A profile’s gpu name appears to match the available GPU, but its gpu_device identifier does not.

Cause: Human-readable gpu formats vary between NIM microservices and are not reliable join keys.

Solution: Match on gpu_device. If only gpu is present, treat the profile as unverified rather than assuming a match. For details, refer to Core Concepts Overview.

Empty tested_gpu_devices on Every Profile#

Symptom: Every profile contains an empty tested_gpu_devices array.

Cause: GPU validation was not recorded for these profiles.

Solution: Treat validation as unrecorded and evaluate the other hardware requirements. An empty array means neither that no GPUs are supported nor that all GPUs are supported. For the GPU targeting signals, refer to Core Concepts Overview.

Expected Fields Are Missing from the Response#

Symptom: A response lacks a field such as min_vram_per_device_gb.

Cause: The response includes only values populated at publish time, and that requirement was not supplied.

Solution: Keep the missing requirement unknown and consult the microservice’s documentation before confirming hardware fit. Retrying or changing endpoint forms does not produce an unrecorded field. For details, refer to Response Fields.

Error Messages#

The following table describes the status codes returned by the read endpoints:

Status Code	Status Code Value	Description	Solution or Workaround
400	`INVALID_REQUEST`	The request is malformed, or stored metadata failed validation on read.	Correct the parameter named in the description. If no parameter is named, report the problem with the request identifier.
404	`NOT_FOUND`	No metadata exists for this NIM microservice and tag.	Confirm the tag and the path form. Accept this result as a normal outcome when coverage does not extend to the NIM microservice.
500	`INTERNAL_ERROR`	An internal error occurred, or stored metadata could not be parsed.	Report the problem with the request identifier and the `resourceId`. Do not retry.

Always log requestStatus.requestId, because that is the value support needs to trace a specific request.