> ## Documentation Index
> Fetch the complete documentation index at: https://checkly-422f444a-mintlify-fcc5020f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Multistep Checks

> Learn how to troubleshoot multistep checks.

Multistep checks are a powerful tool for monitoring complex API workflows. However, they can sometimes be tricky to troubleshoot. Here are some common issues and solutions:

## Expected Non-2xx Responses

**Issue: A step expects a non-2xx response (like a 401, 403, or 404), the API returns it, but the check still fails**

Playwright's `request` fixture does not throw an error on non-2xx status codes. A 403 response is a completed request. If the check fails, an assertion in your test is failing.

The most common cause is `expect(response).toBeOK()`. This assertion only passes for status codes in the 200-299 range, so it fails on an expected 403.

**Solution**: Assert the exact status code you expect instead of using `toBeOK()`:

```typescript theme={null}
await test.step('GET /admin without permissions', async () => {
  const response = await request.get(`${baseUrl}/admin`, { headers })
  expect(response.status()).toBe(403)
})
```

Check the failing assertion in the check result's error log to confirm which expectation caused the failure.

## Authentication and Authorization

**Issue: Authentication failures or token expiration**

**Solutions**:

1. Verify credentials are current and valid
2. Implement token refresh logic for long workflows
3. Check API permissions for all required endpoints
4. Use environment variables for sensitive credentials

## Data Flow Problems

**Issue: Variables not passing correctly between steps**

**Solutions**:

1. Verify variable assignment syntax and scope
2. Add logging to track variable values
3. Check JSON parsing and data extraction logic
4. Validate API response formats match expectations

## Timing and Performance Issues

**Issue: Workflows timing out or running slowly**

**Solutions**:

1. Optimize API performance and database queries
2. Increase timeout values for complex operations
3. Implement parallel processing where possible
4. Add monitoring for long-running operations

## Error Handling and Recovery

**Issue: Workflows failing without proper cleanup**

**Solutions**:

1. Implement try-catch blocks with proper error handling
2. Add cleanup logic in finally blocks
3. Design idempotent operations for safe retries
4. Create rollback procedures for failed transactions