Fix Creem SDK Error: Expected Array, Received Object

Hey guys! Having trouble with the Creem SDK in test mode? Seeing that dreaded "Response validation failed: Expected array, received object" error when calling retrieveCheckout after a successful payment? Don't sweat it; you're not alone! This article breaks down the issue, explains what might be causing it, and provides a comprehensive guide to fixing it so you can get back to building awesome payment integrations. We'll dive deep into the error message, dissect your code, and explore potential solutions, ensuring you have a solid understanding of how to resolve this issue and prevent it in the future. This isn't just about fixing a bug; it's about mastering your craft and delivering seamless payment experiences for your users. So, grab your favorite beverage, buckle up, and let's get started!

Understanding the Error

The error message you're encountering, "Response validation failed: Expected array, received object," indicates a mismatch between the data type the SDK expects and the data type it's receiving in the response from the Creem API. Specifically, the SDK is expecting an array for the feature field, but it's getting an object instead. This usually points to a problem with how the API response is being parsed or how the data is structured on the Creem side, which can happen in test environments due to inconsistent data or mock responses. Understanding the root cause is crucial, and that's what we'll focus on throughout this article. By dissecting the error message and tracing the data flow, we can pinpoint where the discrepancy lies and apply the appropriate fix. Remember, debugging isn't just about finding a solution; it's about learning the system inside and out, making you a more resilient and effective developer.

Dissecting the Error Message

Let's break down the error message piece by piece:

• 2025-08-15T07:16:50.492Z [info] handle creem callback failed: This is a timestamped log entry indicating that the Creem callback handler encountered an error during processing. It's your starting point, the breadcrumb that leads to the root of the problem. Pay close attention to the timestamp, as it can help you correlate the error with specific user actions or system events.
• Error [SDKValidationError]: Response validation failed: This tells us that the SDK's built-in validation mechanism has detected an issue with the response received from the Creem API. SDK validation is crucial for ensuring data integrity and preventing unexpected behavior in your application. It acts as a safety net, catching errors early in the process before they can cause further complications.
• [{ "code": "invalid_type", "expected": "array", "received": "object", "path": ["feature"], "message": "Expected array, received object" }] This is the heart of the error. It pinpoints the exact problem: the feature field in the response was expected to be an array but was received as an object. The code (invalid_type), expected (array), received (object), and path (["feature"]) provide specific details about the type mismatch and its location within the response. This level of detail is invaluable for targeted debugging.
• at ta (.next/server/chunks/9998.js:4:1075) ... at async rA (.next/server/chunks/9998.js:4:43923) These are stack trace entries, showing the sequence of function calls that led to the error. While they might seem intimidating at first, stack traces are powerful tools for tracing the execution flow and identifying the exact line of code where the error originated. Learning to read and interpret stack traces is an essential skill for any developer.
• rawValue: [Object], rawMessage: 'Response validation failed', [cause]: Error [ZodError]: ... This provides additional context about the error, including the raw response object (which might be helpful for inspecting the actual data received) and the underlying ZodError (Zod is a popular schema validation library often used in TypeScript projects). The cause property can contain nested errors, providing a chain of information that can help you understand the error's origin.
• issues: [ [Object] ], addIssue: [Function (anonymous)], addIssues: [Function (anonymous)] These are properties related to the ZodError, providing details about the validation issues encountered. The issues array contains objects describing each validation error, while addIssue and addIssues are methods for programmatically adding validation errors to the ZodError object. These are more relevant if you're working directly with Zod schemas, but understanding their presence can be helpful for advanced debugging.

Common Causes for This Error

Several factors can contribute to this error, especially in a test environment. Here are some common culprits:

1. Mock Data Inconsistencies: In test mode, you're likely using mock data or a sandbox environment. Sometimes, the mock data might not perfectly mirror the structure of the data in the production environment. This can lead to discrepancies where a field expected to be an array is, in fact, an object. It's crucial to ensure your mock data is accurate and consistent with the expected API response schema. This might involve reviewing your mock data definitions, updating them to match the production schema, and even adding validation checks to your test suite to catch these inconsistencies early on.
2. API Changes in Test Environment: The test or sandbox environment might be running a different version of the Creem API than your production environment. This can lead to changes in the response structure, where a field that was previously an array is now an object (or vice-versa). Always check the Creem API documentation for any breaking changes in the test environment and adjust your code accordingly. Regularly syncing your test environment with the latest API changes can prevent these surprises.
3. Incorrect SDK Configuration: While less common, misconfiguration of the SDK itself can sometimes lead to unexpected behavior. Double-check your SDK initialization and configuration settings to ensure they are correct for the test environment. This includes verifying API keys, endpoint URLs, and any other environment-specific settings. A simple typo in a configuration value can lead to a cascade of errors.
4. Data Transformation Issues: In your code, you might be transforming the API response data before it's used by the SDK. If this transformation logic is flawed, it could inadvertently convert an array into an object. Review your data transformation code carefully, paying close attention to the feature field. Debugging tools like console logs or breakpoints can be invaluable for tracing the data flow and identifying where the transformation goes wrong.
5. Creem API Issue (Less Likely): While less likely, there's a chance the issue lies within the Creem API itself, especially in a test environment. There might be a bug in the API that's causing it to return the feature field as an object instead of an array. If you've exhausted all other troubleshooting steps, consider contacting Creem support to report the issue and get their input.

By understanding these common causes, you're already well on your way to resolving the error. The next step is to dive into your code and the Creem API response to pinpoint the exact source of the problem.

Analyzing Your Code

Now, let's get our hands dirty and examine the code you've provided. We'll focus on the key areas that are likely to be involved in this error, such as the retrieveCheckout call, the response handling, and any data transformations. By carefully scrutinizing each part, we can narrow down the possibilities and identify the root cause of the "Expected array, received object" error.

The retrieveCheckout Function Call

The first place to look is the retrieveCheckout function call itself:

const result = await client.creem().retrieveCheckout({
  xApiKey: client.apiKey(),
  checkoutId: checkoutId,
});

This is where you're interacting with the Creem API to fetch the checkout details. Let's consider a few potential issues here:

• Correct Parameters: Ensure that checkoutId is correctly populated with the expected value. An invalid or missing checkoutId could lead to unexpected responses from the API. Double-check that the checkoutId is being passed correctly from the callback URL and that it corresponds to a valid checkout in your test environment. A simple typo or a missing parameter can throw the entire process off.
• API Key: While you're using client.apiKey(), verify that this function is returning the correct API key for your test environment. An incorrect API key could result in authentication errors or unexpected responses. It's good practice to double-check your environment variables and configuration settings to ensure the API key is correct. Using environment-specific API keys is crucial for preventing accidental use of production keys in test environments and vice-versa.
• Network Issues: Although less likely to cause this specific error, intermittent network issues could lead to incomplete or corrupted responses. Check your network connectivity and ensure there are no firewalls or other network restrictions that might be interfering with the API call. You can also use tools like curl or Postman to test the API endpoint directly and rule out any network-related problems.

Response Handling and Validation

Next, let's look at how you're handling the response from retrieveCheckout:

if (result.requestId !== requestId) {
  throw new Error("invalid checkout data");
}

if (!result.order || result.order.status !== "paid") {
  throw new Error("invalid order status");
}

if (
  !result.customer ||
  typeof result.customer === "string" ||
  !("email" in result.customer)
) {
  throw new Error("invalid customer email");
}

This section of your code performs several validations on the response data. While these checks are good for ensuring data integrity, they don't directly address the "Expected array, received object" error. However, they give a context to where the error might occur, since the error occurred before these validation checks.

Data Transformation and Usage

The final part of your code that's relevant is where you're extracting data from the result and using it to update the order:

const order_no = result.requestId;
const paid_email = result.customer.email;
const paid_detail = JSON.stringify(result);

await updateOrder({ order_no, paid_email, paid_detail });

Here, you're extracting requestId, customer.email, and stringifying the entire result object. The stringification itself shouldn't cause the error, but it's essential to examine what's inside the result object. This is where the feature field resides, and if it's an object instead of an array, that's where the problem lies.

To further investigate, you can add a console.log(result) statement before the JSON.stringify line to inspect the structure of the result object directly. This will allow you to see the actual value of the feature field and confirm whether it's an object or an array. This is a crucial step in pinpointing the source of the error.

Identifying the Root Cause

By carefully examining your code and the error message, we can formulate a few hypotheses:

1. The feature field is indeed an object in the response: This is the most likely scenario, given the error message. To confirm this, you need to inspect the result object using console.log(result).
2. There's a data transformation issue: Although less likely, it's possible that some code (not shown in the provided snippet) is transforming the API response and inadvertently converting the feature array into an object.
3. The Creem API is returning an incorrect response in the test environment: This is also possible, especially in a test environment where things might not be as stable as in production.

To move forward, you need to gather more information. Adding console.log(result) is the first step. Once you've inspected the result object, you'll have a clearer picture of what's going on and can take the appropriate action.

Troubleshooting Steps and Solutions

Alright, let's dive into some practical steps you can take to troubleshoot and fix this issue. We'll cover everything from inspecting the API response to adjusting your code and configurations. Remember, debugging is a process of elimination, so be patient and methodical as you work through these steps.

1. Inspect the API Response

The most crucial step is to inspect the raw API response. Add a console.log(result) statement right after the const result = await client.creem().retrieveCheckout(...) line in your code. This will print the entire response object to your console, allowing you to see the actual structure and data being returned by the Creem API.

const result = await client.creem().retrieveCheckout({
  xApiKey: client.apiKey(),
  checkoutId: checkoutId,
});
console.log("Creem API Response:", result); // Add this line

Once you've added this line, trigger the payment flow in your test environment and check your console output. Look for the feature field in the response. Is it an object or an array? If it's an object, this confirms the error message's diagnosis. If it's an array, then the issue lies elsewhere, and we'll need to explore other possibilities.

2. Verify Mock Data (If Applicable)

If you're using mock data in your test environment, it's essential to ensure that the mock response for the retrieveCheckout API call is accurate. Check your mock data definition and verify that the feature field is an array and that its contents match the expected structure.

Inconsistent mock data is a common cause of errors in test environments. Make sure your mock data is up-to-date and reflects the actual API response schema. You might even consider using a tool to automatically generate mock data from your API schema, which can help prevent these kinds of inconsistencies.

3. Check Creem API Documentation

Refer to the Creem API documentation for the retrieveCheckout endpoint. Verify the expected response structure and data types, especially for the feature field. The documentation will provide a definitive answer as to whether feature should be an array or an object.

API documentation is your best friend when troubleshooting API-related issues. It's the source of truth for understanding how the API is supposed to work and what data it's supposed to return. Always consult the documentation before making assumptions about the API's behavior.

4. Contact Creem Support

If the API documentation indicates that feature should be an array, and you're receiving an object in the test environment, it's possible there's an issue with the Creem API itself. In this case, reach out to Creem support and report the problem. Provide them with the details of your issue, including the error message, the steps you've taken to troubleshoot, and the output of your console.log(result) statement.

Creem support can investigate the issue on their end and provide you with guidance or a fix. They might be aware of a bug in the test environment or have other insights that can help you resolve the problem.

5. Adjust Your Code (If Necessary)

If the feature field is indeed an object, and it's supposed to be an array, you'll need to adjust your code to handle this discrepancy. This might involve:

• Transforming the object into an array: If the object contains the data you need, you can transform it into an array using JavaScript's built-in methods or a custom function. For example, if the object has keys that represent array indices, you can iterate over the keys and create an array from the corresponding values.
• Handling the object as an object: If the object structure is consistent and you can work with it directly, you might choose to adjust your code to handle the object instead of expecting an array. This might involve changing how you access the data within the feature field.

However, before making any code changes, make sure you understand why the API is returning an object instead of an array. If it's a bug in the API, the fix might be on the Creem side, and your code changes might become obsolete once the bug is resolved. It's always best to understand the root cause before implementing a workaround.

6. Implement Error Handling and Logging

Even after you've fixed the immediate issue, it's crucial to implement robust error handling and logging in your code. This will help you catch and diagnose similar issues in the future. Consider adding error boundaries, try-catch blocks, and detailed logging statements to your code.

Good error handling and logging practices are essential for building resilient applications. They allow you to gracefully handle unexpected errors, provide informative error messages to users, and quickly diagnose and fix issues when they arise. Think of error handling and logging as an investment in the long-term maintainability and stability of your application.

Example Fix (If feature is an Object)

Let's say the feature field is an object with keys like `