> AI agents: this is one page from Mammoth Analytics documentation. The index of all pages as Markdown is https://docs.mammoth.io/llms.txt. Append `.md` to any docs URL, or send `Accept: text/markdown`, to get Markdown.

# Error messages reference

> Reference of common Mammoth errors and HTTP status codes (401, 403, 429), grouped by area, with the cause and fix for each.

This reference covers the errors people most often run into in Mammoth, with the cause and fix for each. Where Mammoth shows a fixed message, the heading uses its exact text. Other headings describe the problem in plain words, because the wording on screen varies. Each entry lists common causes and steps to fix it.

## How to use this guide

**Find your error**: Use Ctrl+F to search for the error text you're seeing, or scan the headings for the closest description.

**Understand the Cause**: Each error explains why it happened, not just what went wrong.

**Follow Solutions**: Try solutions in order—they're ranked from most common to advanced fixes.

**Check the Activity Log**: The Activity Log records changes made in a project or workspace, such as edits, connection changes and pipeline re-runs. Use it to match an error to a recent change.

## Authentication errors

### Sign-in or API credentials rejected (401)

**What it means**: Your sign-in credentials or API token are invalid, expired or missing, and the request is refused with HTTP status 401.

**Common causes**:

- Session expired after inactivity
- Browser cleared cookies automatically
- Password changed in another session
- Multi-factor authentication code expired
- API token missing or incorrect

**Solutions**:

1. **Sign out and sign back in** - Clears any corrupted session data
2. **Clear browser cookies** for mammoth.io - Remove cached authentication
3. **Check your MFA code** - Ensure the time on your authenticator app is synchronized
4. **Reset password** if you can't remember current password
5. **For API users**: Verify that your API token is present in the request and still valid

If you're getting frequent session timeouts, check if your company's network has aggressive cookie policies that might be clearing authentication tokens.

### Permission denied (403)

**What it means**: You're signed in but don't have permission for this action, and the request is refused with HTTP status 403. Mammoth can report this as "User lacks permission to perform given action".

**Common causes**:

- Your role doesn't allow the action (for example, a Project Editor trying to delete the project)
- Project access was revoked
- Workspace membership removed
- Feature requires higher subscription tier

**Solutions**:

1. **Check your role** with a project or workspace admin
2. **Ask an admin** to grant the permissions you need
3. **Review the Activity Log** for recent changes to your workspace membership
4. **Verify feature availability** in your current plan
5. **Switch to correct workspace** if you have multiple memberships

### Connection authentication expired

**What it means**: Credentials for your external data source have expired or are no longer accepted.

**Common causes**:

- OAuth tokens expired
- Password changed in source system
- API key rotated by external service
- SAML/SSO session timeout

**Solutions**:

1. **Open the connection** and re-enter or reauthorize your current credentials
2. **Test the connection** before running automations
3. **Note the expiration date** of tokens and keys for future renewal planning

## Schema and column errors

When you add data to an existing dataset, Mammoth lines up columns by name. Extra columns in the new data are added, columns missing from the new data are filled with nulls, and columns whose data types differ trigger a column-mapping step.

### New data can't be combined because the schemas don't match

**What it means**: The new data can't be combined with the existing dataset because its schema doesn't match. Mammoth reports this as `Datasources with mismatching schemas cannot be appended`.

**Common causes**:

- File template changed without updating Mammoth
- Column accidentally deleted or renamed during export
- Wrong file uploaded (different source)

**Solutions**:

1. **Compare the file to a previous upload** - Check which columns are missing, renamed or new
2. **Re-export from the source** ensuring all columns are included and named as before
3. **Use Replace instead of Combine** if the new file is meant to overwrite the dataset
4. **Create a new dataset** if the file structure has fundamentally changed

> **Share a template with data suppliers**
>
> Create a master file template with sample data and share it with all data suppliers. Include column names, data types, and example values to prevent schema mismatches.

### Some columns were converted to text

**What it means**: A Numeric or Date column contained values that couldn't be read as that type, so Mammoth converted the column to text. The message reads "Some of the Numeric or Date columns had error values, these columns have been converted to text columns".

**Examples**:

- A Number column with "N/A" in some rows
- A Date column with "TBD" in some rows

**Solutions**:

1. **Review source data** for data quality issues
2. **Clean the data before upload** - Remove or replace invalid values
3. **Use the Convert Column Type task** in the pipeline to convert the column back once the values are clean
4. **Add data validation** in the source system to prevent future issues

**Common data type fixes**:

```plaintext
Revenue column with "N/A" → Use Fill Missing Values or Conditional Filter to handle the rows
Date column with "TBD" → Use Conditional Filter → Remove invalid rows
ID column with leading zeros → Keep as Text type, don't convert to Number
```

## Transformation errors

### A calculation fails or returns blanks because of empty values

**What it means**: A mathematical operation or type conversion ran into empty/missing data.

**Common examples**:

- A Math Function on a column that contains blanks
- A Convert Column Type on a column with empty cells

**Solutions**:

1. **Add a Fill Missing Values task** before mathematical operations
2. **Use Conditional Filter** to remove null rows before calculation
3. **Check data quality** with the Data Quality Report to identify null patterns
4. **Handle nulls in the source system** before export

**Fill Missing Values methods**:

- **Directional**: Copy the closest value above or below in the column
- **Smart**: Predict each empty cell from the rest of the data

### "Invalid date format"

**What it means**: Date text doesn't match the expected format pattern. A Conditional Filter on a date column shows this as "Invalid date format for [value] in condition".

**Common format issues**:

- Mixed formats: "01/15/2024" and "2024-01-15" in same column
- Ambiguous formats: "01/02/2024" (Jan 2 or Feb 1?)
- Non-date text: "Next Week", "TBD", "Q4 2024"
- Time zones: Dates with different timezone indicators

**Solutions**:

1. **Standardize format in source** - Export with consistent date format
2. **Use "Convert Column Type"** with specific format pattern
3. **Handle multiple formats** with conditional transformation
4. **Document expected format** for data suppliers
5. **Filter out invalid dates** before date operations

**Date format examples**:

```plaintext
Excel Export → Use "Short Date" format: MM/DD/YYYY
Database Export → Use ISO format: YYYY-MM-DD
Manual Entry → Provide template: "01/31/2024"
```

### A join returns no matching rows

**What it means**: The join keys in your two datasets don't have any matching values.

**Common causes**:

- Case sensitivity: "CUSTOMER001" vs "customer001"
- Whitespace: "ABC " vs "ABC" (trailing space)
- Data type mismatch: Text "123" vs Number 123
- One dataset has no matching records

**Solutions**:

1. **Preview join keys** from both datasets side by side
2. **Apply text formatting** (Trim, Upper Case) before join
3. **Convert data types** to match (both text or both number)
4. **Use a Left join** to keep every row of the current view and see which records don't match
5. **Check for typos** in join key values

**Debugging joins**:

```plaintext
1. Create a View from Dataset A, select join column only
2. Create a View from Dataset B, select join column only
3. Compare distinct values between both Views
4. Identify formatting differences
5. Apply standardization before attempting join
```

## File upload errors

### The file is too large

**What it means**: Your file is larger than the upload limit. A file upload can be up to 50 MB on every plan, and a larger request is refused. See [limits and quotas](https://docs.mammoth.io/learn/limits-and-quotas).

**Solutions**:

1. **Split the file into smaller chunks** - Upload separately then combine
2. **Filter data in the source system** - Export only needed columns and rows
3. **Remove unnecessary columns** before export
4. **Use a connection to the source** instead of a file upload for large datasets

> **Large recurring files**
>
> For recurring large files, connect to the source system directly instead of uploading files.

### Unsupported file type

**What it means**: The file type you uploaded isn't supported by Mammoth. The message reads "Unsupported file type".

**Supported file types for upload**:

- **Text and delimited files**: `.txt`, `.csv`, `.tsv`, `.psv`
- **Excel**: `.xls`, `.xlsx`
- **XML**: `.xml`
- **Archives and compressed files**: `.zip`, `.gz`, `.bz2`, `.tar`, `.7z`
- **PDF and image files**: `.pdf`, `.tiff`, `.tif`, `.jpeg`, `.jpg`, `.png`, `.heic`, `.heif`, `.webp` (availability depends on your plan and workspace settings)

Adding or replacing data in a dataset with a ZIP file that contains multiple items isn't allowed.

**Solutions**:

1. **Convert to CSV** - Universal format that works everywhere
2. **Export as Excel** from your source application
3. **Check that the file extension** matches the actual content
4. **Re-download the file** if it might be corrupted. Mammoth reports a damaged file as "File seems to be corrupt" and an empty file as "File is empty"
5. **Use a data connector** for sources that don't export to a supported file type, such as JSON or Parquet

### Characters look wrong after upload

**What it means**: The file uses a character encoding other than the one Mammoth expects, so special characters appear garbled.

**Common encoding issues**:

- Latin-1 encoding from legacy systems
- Windows-1252 with special characters
- Excel exports with international characters

**Solutions**:

1. **Use the "CSV UTF-8" option** when exporting from Excel
2. **Convert the encoding** in a text editor (Notepad++, VS Code)
3. **Re-export from the source system** with a UTF-8 setting
4. **Contact support** for assistance with specific encoding

**Excel UTF-8 export**:

```plaintext
1. File → Save As
2. Choose "CSV UTF-8 (Comma delimited)"
3. Click Save
4. Upload the new .csv file to Mammoth
```

## Automation errors

### A Dataset Refresh can't connect to the source

**What it means**: A scheduled data refresh couldn't connect to your data source.

**Common causes**:

- Connection authentication expired
- Source system temporarily down
- Network/VPN connectivity issues
- Source system rate limiting requests

**Solutions**:

1. **Check the connection** and confirm its credentials are still valid
2. **Test the connection manually** outside of the automation
3. **Reconnect with current credentials** if expired
4. **Verify source system status** - Check if the system is online
5. **Review the Activity Log** for recent changes to the connection or automation

### A Data Consolidation fails on a new file

**What it means**: A file added to your automated consolidation doesn't match the existing dataset's schema.

**Common scenarios**:

- Supplier changed file format without notice
- Wrong file uploaded to monitored folder
- Column names changed
- Required columns missing from new file

**Solutions**:

1. **Review the failing file** - Download and inspect structure
2. **Compare to file template** you provided to suppliers
3. **Contact data supplier** about format changes
4. **Update the pipeline or dataset** if the change is permanent
5. **Provide a corrected template** to prevent future mismatches

**Preventing consolidation errors**:

- Document exact schema requirements
- Provide sample files with correct format
- Set up validation in supplier systems

### A pipeline task fails

**What it means**: A specific transformation task in your pipeline encountered an error and stopped execution.

**Common task failures**:

- **Conditional Filter**: Invalid filter criteria
- **Join**: No matching records between datasets
- **Math Function**: Division by zero or null values
- **Find & Replace**: Invalid patterns

**Solutions**:

1. **Turn on Draft mode** to test pipeline changes safely
2. **Preview the pipeline step by step** up to the failing task
3. **Inspect the data before the failing task** to understand the input
4. **Review the task configuration** for errors

**Debugging pipeline failures**:

```plaintext
1. Open the View with the failed pipeline
2. Find the task that shows the error
3. Review the error message and the data feeding the task
4. Edit the task configuration
5. Check the result in the preview before applying changes
```

## Performance errors

### An operation times out

**What it means**: Your operation took longer than the allowed time and was cancelled.

**Common causes**:

- Processing very large datasets
- Complex pipelines with many transformation tasks
- Network latency during upload/download
- Server load during peak usage times

**Solutions**:

1. **Filter dataset to smaller subset** for testing
2. **Simplify pipeline** - Break into multiple smaller pipelines
3. **Use Draft mode** to batch several pipeline changes before running them
4. **Run during off-peak hours** if server load is a factor
5. **Contact support** if timeouts persist with normal-sized data

**Performance optimization tips**:

- Filter early in pipeline to reduce data volume
- Combine similar operations (multiple filters → single conditional filter)
- Use the Top/Bottom Filter or Limit Rows task for sampling large datasets
- Process data incrementally rather than all at once

### "Rate limit exceeded." (429)

**What it means**: You've sent too many API requests in the current one-minute window. The API answers with HTTP status 429, the message "Rate limit exceeded." and a `Retry-After: 60` header.

**Solutions**:

1. **Slow down request frequency** - Add delays between operations
2. **Batch operations** instead of individual API calls
3. **Wait for the time in the `Retry-After` header** (60 seconds), then try again
4. **Honour `Retry-After`** in API integrations before retrying
5. **Contact support** if you keep hitting the limit with normal usage

**API rate limit handling**:

```python
import time
import requests

def api_call_with_retry(url, data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, json=data)
        if response.status_code != 429:
            return response

        # Wait as long as the server asks (60 seconds by default)
        wait_time = int(response.headers.get("Retry-After", 60))
        time.sleep(wait_time)

    return response  # Final attempt
```

## Dashboard errors

### A dashboard can't load its data

**What it means**: The dashboard can't access the underlying dataset or View.

**Common causes**:

- Dataset or View was deleted or moved
- View permissions changed
- Project access revoked
- Automation failure preventing data updates

**Solutions**:

1. **Verify dataset exists** in original project location
2. **Check project access permissions** - You may have lost access
3. **Review the Activity Log** for dataset deletions or moves
4. **Recreate the dashboard** from a current View if the original is permanently gone

### A chart doesn't display

**What it means**: The dashboard can't display a specific chart or visualization. When a column a chart uses has been removed from the View, the tile reports that the column "is no longer available".

**Common causes**:

- A column used by the chart was renamed or removed in the View
- Incompatible data for the selected chart (text data in a line chart)
- Browser memory limitations
- Invalid chart configuration

**Solutions**:

1. **Check the View** for renamed or removed columns, and restore them or rebuild the chart
2. **Filter the data** to a smaller date range or subset
3. **Change the chart type** - Use a table for high-cardinality data
4. **Simplify the visualization** - Fewer data series or dimensions
5. **Refresh the browser** to clear memory, then clear the browser cache if the problem persists

## Error prevention best practices

### Practice 1: Use templates and documentation

**Create standardized templates**:

- File format templates for data suppliers
- Column naming conventions
- Data type specifications
- Example data for clarity

**Document requirements**:

- Required vs optional columns
- Expected data formats
- The 50 MB file size limit (see [limits and quotas](https://docs.mammoth.io/learn/limits-and-quotas))
- Update frequencies

### Practice 2: Validate early and often

**Before uploading large files**:

1. Test with small sample first (100 rows)
2. Use Data Quality Report to check completeness
3. Verify schema matches previous uploads
4. Review for obvious data quality issues

**Before building complex pipelines**:

1. Start with simple transformations
2. Test each step with Preview
3. Use Draft mode to try changes before applying them
4. Save working versions before major changes

### Practice 3: Monitor connection health

**Set up monitoring**:

- Check your connections weekly
- Document authentication expiration dates
- Test connections before important automations
- Set calendar reminders for credential renewals

**Document connection details**:

- Who owns/maintains each connection
- Authentication renewal process
- Backup contact information
- Emergency procedures

### Practice 4: Review Activity Log regularly

**Regular Activity Log review**:

- Look for unexpected edits, connection changes and pipeline re-runs
- Monitor user activity

**Use the Activity Log for troubleshooting**:

- Filter by date range or event
- Share relevant entries with support for complex issues
- Correlate errors with recent changes

> **Activity Log filters**
>
> Use the Activity Log filters to narrow the log to a date range and see which change happened just before a problem started.

## When to contact support

### Contact support immediately for

- 500 Internal Server Error - System-level issues
- Data corruption - Incorrect results after transformation
- Security concerns - Unauthorized access or permission issues
- Billing problems - Incorrect charges or plan questions

### Contact support after trying solutions for

- Persistent timeouts - Even with optimized operations
- Connection issues - After verifying credentials and network
- Repeated automation failures - Same error multiple times
- Performance degradation - Sudden slowness across all operations

### Include in your support request

1. Exact error message - Copy/paste the complete text
2. Steps to reproduce - What you were doing when error occurred
3. Activity Log entries - Relevant timestamps and recent changes
4. Browser/system info - Version, extensions, network setup
5. Data examples - Sample files or schema (remove sensitive data)

## Quick error lookup

- Can't sign in: see [Authentication errors](#authentication-errors)
- File won't upload: see [File upload errors](#file-upload-errors)
- Pipeline fails: see [Transformation errors](#transformation-errors)
- Columns or schema don't match: see [Schema and column errors](#schema-and-column-errors)
- Slow performance: see [Performance errors](#performance-errors)
- Dashboard broken: see [Dashboard errors](#dashboard-errors)
- Automation fails: see [Automation errors](#automation-errors)
- API returning errors: see [Authentication errors](#authentication-errors) for 401 and 403 and [Performance errors](#performance-errors) for 429

---
Source: https://docs.mammoth.io/learn/troubleshooting/errors.md · Updated: 2026-10-13