Skip to content
Try free
Learn › Troubleshooting: open the docs menu

Error messages reference

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

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:

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:

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:

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.

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

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:

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:

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:

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)
  • 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

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

Report an issue · support@mammoth.io