Compute API launchInstance fails with 'InvalidParameter' when using custom shapes

Cloud Platforms Oracle Cloud
, , , , , , , ,
1

I’m hitting an ‘InvalidParameter’ error when trying to launch VM instances via the oci-2021 Compute API with custom shapes. The same configuration works perfectly fine through the OCI Console, but the API call consistently fails.

Here’s the error I’m getting:


HTTP 400: InvalidParameter
"shape": "VM.Standard.E4.Flex" requires ocpus and memoryInGBs

My API request includes:

{
  "shape": "VM.Standard.E4.Flex",
  "compartmentId": "ocid1.compartment...",
  "availabilityDomain": "AD-1"
}

The error message mentions ocpus and memoryInGBs are required for flex shapes, but the console doesn’t explicitly ask for these when I select the same shape. What are the exact required fields for custom shapes via the API that differ from the console experience? Are there shape-specific validation rules I’m missing?

2

One thing that caught me off guard: the API also validates shape availability per availability domain differently than the console. The console might show a shape as available because it checks across all ADs, but your API call targets a specific AD. If you’re getting InvalidParameter after adding shapeConfig correctly, verify the shape is actually available in your specified availabilityDomain using the ListShapes API with the compartmentId and availabilityDomain filters. The error messages can be misleading when it’s actually a capacity issue disguised as a parameter problem.

3

I ran into this exact issue last month. The shapeConfig goes at the same level as your shape parameter in the launchInstanceDetails. For E4.Flex specifically, ocpus must be between 1-64, and memory ratio is 1:1 to 1:64 per OCPU. So if you specify 2 ocpus, memoryInGBs can range from 2 to 128. The API enforces these ratios strictly while the console guides you with dropdown constraints. Make sure your JSON structure matches the LaunchInstanceDetails schema exactly - nested objects matter for validation.

4

The console auto-populates default values for flex shapes, but the API requires explicit parameters. For VM.Standard.E4.Flex, you must specify both ocpus and memoryInGBs in a shapeConfig object. The console hides this complexity by using defaults (typically 1 OCPU and 16GB memory), but the API validation is stricter. Add a shapeConfig block to your request body with these required fields.

5

Thanks for the pointer. I tried adding shapeConfig but still getting validation errors. Should this be nested under the main request body or within a specific configuration section? Also, are there minimum/maximum values I need to respect for the E4.Flex series? The API documentation seems sparse on the actual validation constraints.

6

Let me break this down completely. I’ve been working with the Compute API since oci-2019 and the validation rules have gotten stricter.

Shape Parameter Validation: Flex shapes require explicit resource allocation. The API won’t assume defaults like the console does. You must provide ocpus (integer) and memoryInGBs (float) within shapeConfig.

API vs Console Differences: The console performs client-side validation and pre-fills compatible values. The API validates server-side against actual resource constraints. Console shows you dropdowns with valid ranges; API expects you to know them. Check the shape’s specifications using GET /shapes/{shapeId} to see min/max values.

Required Fields for Custom Shapes: Here’s a working structure:

{
  "shape": "VM.Standard.E4.Flex",
  "shapeConfig": {
    "ocpus": 2,
    "memoryInGBs": 32
  }
}

Critical points:

  1. shapeConfig is a sibling to shape, not nested deeper
  2. ocpus is integer, memoryInGBs accepts float (e.g., 32.0 or 32)
  3. Validate memory-to-OCPU ratio: E4.Flex allows 1GB to 64GB per OCPU
  4. Some shapes require additional fields like baselineOcpuUtilization for burstable instances
  5. Always include compartmentId, availabilityDomain, imageId, and subnetId as mandatory fields

Common Mistakes:

  • Placing shapeConfig inside createVnicDetails or instanceOptions
  • Using string values instead of numeric types
  • Forgetting that shape names are case-sensitive
  • Not checking shape availability per AD before calling launchInstance

Debugging Approach:

  1. Use ListShapes API filtered by compartment and AD to get exact shape specs
  2. Verify your JSON schema matches LaunchInstanceDetails exactly
  3. Check API version compatibility - oci-2021 introduced stricter validation than earlier versions
  4. Enable detailed error responses in your API client to see full validation messages

If you’re still getting InvalidParameter after these corrections, share your complete request body (redact sensitive OCIDs) and the full error response. The API usually returns specific field names in the error details that pinpoint the exact validation failure.