> This page is for version 1.0.0 (Latest) (default). > For other versions, use one of these documentation indexes: > - 1.0.0 (Latest) (default): https://docs.nvidia.com/nim/metadata-api/1.0.0/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nim/metadata-api/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nim/metadata-api/_mcp/server. # Troubleshooting NIM Metadata API > Resolve unexpected status codes, missing fields, and GPU matching problems when you query the NIM Metadata API. The following issues might arise when you work with the [NIM Metadata API](/nim/metadata-api/about/overview). 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](/nim/metadata-api/reference/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: 1. Confirm the exact container tag. Metadata is stored per tag, so metadata for `1.2.0` says nothing about `1.2.1`. 2. Confirm whether the repository belongs to a team. If `nim/{repo}` fails for a team-owned NIM microservice, use `nim/{team}/{repo}`. 3. 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](/nim/metadata-api/guides/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](/nim/metadata-api/reference/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](/nim/metadata-api/about/core-concepts). ## 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](/nim/metadata-api/about/core-concepts). ## 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](/nim/metadata-api/reference/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. ## Related Topics * [Endpoints](/nim/metadata-api/reference/endpoints) * [Current Limitations](/nim/metadata-api/reference/limitations) * [Prerequisites](/nim/metadata-api/get-started/prerequisites) * [Notes for Automated Agents](/nim/metadata-api/guides/automated-agents)