> ## Documentation Index
> Fetch the complete documentation index at: https://docs.milkstraw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions when using MilkStraw AI.

This guide covers common issues you might encounter and how to resolve them.

## Connection issues

### IAM role connection failed

<AccordionGroup>
  <Accordion title="Error: Unable to assume IAM role">
    **Cause**: The IAM role may not have the correct trust relationship or permissions.

    **Solution**:

    1. Verify the CloudFormation stack deployed successfully
    2. Check that the trust policy includes MilkStraw AI's account ID
    3. Ensure the role has the required least-privilege permissions
    4. Try reconnecting in the dashboard

    See [Permissions](/permissions) for required IAM policies.
  </Accordion>

  <Accordion title="Error: Cost Explorer API not enabled">
    **Cause**: Cost Explorer API is not enabled in your AWS account.

    **Solution**:

    1. Go to AWS Cost Explorer in your management account
    2. Enable Cost Explorer (may take up to 24 hours to activate)
    3. Wait for activation to complete
    4. Reconnect your account in MilkStraw AI dashboard
  </Accordion>

  <Accordion title="Error: Insufficient permissions">
    **Cause**: The IAM role is missing required permissions.

    **Solution**:

    1. Review the CloudFormation template
    2. Ensure all required policies are attached
    3. Update the stack if needed
    4. Verify permissions in IAM console
  </Accordion>
</AccordionGroup>

## MilkBox issues

### MilkBox not appearing in AWS

<AccordionGroup>
  <Accordion title="MilkBox approved but not visible">
    **Cause**: MilkBox creation can take 15-30 minutes.

    **Solution**:

    1. Wait 30 minutes after approval
    2. Check the MilkBox account in your AWS Organization
    3. Verify the account is active and not suspended
    4. Contact support if still not visible after 1 hour
  </Accordion>

  <Accordion title="Commitment not being applied">
    **Cause**: Commitment may not match your usage patterns or regions.

    **Solution**:

    1. Verify the commitment type matches your workload
    2. Check that usage is in the same region (for EC2 Instance Savings Plans)
    3. Review commitment details in AWS Billing console
    4. Allow 24-48 hours for full application
  </Accordion>
</AccordionGroup>

## Billing issues

### Savings not showing in dashboard

<AccordionGroup>
  <Accordion title="Expected savings not reflected">
    **Cause**: Savings data can take 24-48 hours to appear in Cost Explorer.

    **Solution**:

    1. Wait 48 hours after MilkBox deployment
    2. Verify commitments are active in AWS Billing console
    3. Check that Cost Explorer is showing commitment utilization
    4. Contact support if savings still not visible after 72 hours
  </Accordion>

  <Accordion title="MilkStraw AI fee seems incorrect">
    **Cause**: Fee calculation may be based on different time period or savings calculation.

    **Solution**:

    1. Review the billing period in your invoice
    2. Check the savings calculation in Cost Explorer
    3. Verify the 20% fee is applied to actual savings
    4. Contact support with specific invoice details
  </Accordion>
</AccordionGroup>

## Performance issues

### Low commitment utilization

<AccordionGroup>
  <Accordion title="Utilization below 80%">
    **Cause**: Usage patterns may have changed or commitment was oversized.

    **Solution**:

    1. Review recent infrastructure changes
    2. Check if workloads were scaled down or terminated
    3. Wait for MilkStraw AI to adjust recommendations
    4. Consider modifying or exchanging commitments (for Convertible RIs)
  </Accordion>

  <Accordion title="Coverage rate is low">
    **Cause**: Not enough commitments purchased or new workloads added.

    **Solution**:

    1. Review pending recommendations in dashboard
    2. Approve additional MilkBoxes to increase coverage
    3. Ensure automatic approval is enabled for optimal coverage
    4. Allow time for AI to analyze new usage patterns
  </Accordion>
</AccordionGroup>

## Dashboard issues

### Data not updating

<AccordionGroup>
  <Accordion title="Dashboard shows stale data">
    **Cause**: Data sync may be delayed or connection issue.

    **Solution**:

    1. Refresh the page
    2. Check your internet connection
    3. Verify IAM role connection is still active
    4. Wait 15 minutes and try again
    5. Clear browser cache if issue persists
  </Accordion>

  <Accordion title="Cannot approve MilkBoxes">
    **Cause**: Browser issue or permission problem.

    **Solution**:

    1. Try a different browser
    2. Disable browser extensions
    3. Check that you have approval permissions in your MilkStraw AI account
    4. Contact support if issue continues
  </Accordion>
</AccordionGroup>

## Getting help

If you can't resolve your issue using this guide:

<CardGroup cols={2}>
  <Card title="Check FAQ" icon="circle-question" href="/faq">
    Review frequently asked questions
  </Card>

  <Card title="Contact support" icon="headset" href="/contact">
    Schedule a call or reach out via Slack
  </Card>
</CardGroup>

## Diagnostic checklist

Before contacting support, gather this information:

<Steps>
  <Step title="Account details">
    * Your MilkStraw AI account email
    * AWS account ID(s) affected
    * When the issue started
  </Step>

  <Step title="Error messages">
    * Screenshots of any error messages
    * Browser console errors (if dashboard issue)
    * AWS CloudFormation stack events (if deployment issue)
  </Step>

  <Step title="What you've tried">
    * Steps you've already taken to resolve the issue
    * Any changes made before the issue occurred
  </Step>
</Steps>

<Warning>
  For urgent issues affecting active commitments or billing, contact support immediately via [scheduled call](https://cal.com/team/milkstraw-ai/chat-with-milkstraw-team).
</Warning>