oracle / oracle/oci-cli

JSON format error message should include the received input value for easier debugging

Open Beginner friendly
#1,110 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
669
Forks
236
Avg merge
1m
Merged PRs (30d)
4

Description

Description

When passing complex JSON parameters (--nsg-ids, --metadata, --defined-tags, --shape-config, etc.) with invalid JSON, the error message is opaque: it uses the internal Python parameter name (lisp_case) instead of the CLI flag the user typed, and does not echo back the received value.

Steps to Reproduce

NSG_ID="ocid1.networksecuritygroup.oc1..example"
oci compute instance launch ... --nsg-ids "[$NSG_ID]"

Expected Behaviour

The error should include:

  1. The actual CLI flag the user typed (--nsg-ids, not nsg_ids)
  2. The received input value so the user can see what was parsed
  3. A concrete example of valid input
Parameter '--nsg-ids' (received as '[ocid1.networksecuritygroup.oc1..example]')
must be valid JSON. Example: --nsg-ids '["ocid1.networksecuritygroup.oc1..example"]'

Actual Behaviour

Parameter 'nsg_ids' must be in JSON format.
For help with formatting JSON input see our documentation here: https://docs.cloud.oracle.com/iaas/Content/API/SDKDocs/cliusing.htm#ManagingCLIInputandOutput

Problems:

  1. The error says nsg_ids (Python internal name) but the user typed --nsg-ids.
  2. The received value is not shown, making it hard to see what Bash actually parsed.
  3. The user is sent to external documentation instead of getting an inline example.

Context

This is a common stumbling block for Bash users. The safe pattern for embedding variables in JSON array parameters is non-obvious:

# ❌ Bash strips the inner quotes; fails
--nsg-ids "[$NSG_ID]"

# ✅ Backslash-escaped inner quotes; works
--nsg-ids "[\"$NSG_ID\"]"

The existing error message's source code is in src/oci_cli/cli_util.py:

sys.exit('Parameter {!r} must be in JSON format.\nFor help with formatting JSON input ...'.format(parameter_name))

Suggested Fix

Include the received input in the error message so users can see exactly what was parsed:

sys.exit('Parameter {!r} (received as {!r}) must be valid JSON.\nExample: --nsg-ids \'["ocid1.networksecuritygroup..."]\'\nFor more help see: https://docs.cloud.oracle.com/ias/Content/API/SDKDocs/cliusing.htm#ManagingCLIInputandOutput'.format(parameter_name, user_input))

Also consider mapping the internal parameter name back to the CLI flag name (e.g., nsg_ids--nsg-ids) for user-facing output.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in src/oci_cli/cli_util.py at the JSON parsing error shown in the issue, then run the provided --nsg-ids reproduction to inspect the current output. Trace how the internal parameter name, CLI flag, and received value are available, and consider existing tests around CLI input errors. Done means invalid JSON reports the typed flag, received value, and a concrete valid-input example.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
75/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.