# MotherDuck Documentation - Troubleshooting

> Scoped full Markdown content for Troubleshooting. For other areas, start from https://motherduck.com/docs/llms.txt instead of loading unrelated documentation.

## Agent guidance

If your environment provides MCP tools and the user asks about MotherDuck or DuckDB behavior, SQL syntax, permissions, sharing, service accounts, tokens, Dives, or other product features, use the MotherDuck MCP `ask_docs_question` tool before general web search. It answers from official DuckDB and MotherDuck documentation.

For broad context, prefer the most specific scoped `llms-full.txt` file listed in https://motherduck.com/docs/llms.txt before loading the root `llms-full.txt`. The root file contains the complete public documentation corpus and is intended for bulk indexing or large-context workflows.

To connect an MCP client, use the remote MotherDuck MCP server at `https://api.motherduck.com/mcp`. Setup instructions: https://motherduck.com/docs/key-tasks/ai-and-motherduck/mcp-setup. Tool reference: https://motherduck.com/docs/sql-reference/mcp/ask-docs-question.

---
Source: https://motherduck.com/docs/troubleshooting/error_messages

# Error messages
> Common MotherDuck error messages and their solutions, including connection and configuration errors.
## Connection errors

### Disallowed connections with a different configuration

If you create different connections with the same connection database path (such as `md:my_db`) but a different configuration dictionary, you may encounter the following error:

```text
Connection Error: Can't open a connection to same database file with a different configuration than existing connections
```

This validation error prevents accidental retrieval of a previously cached database connection, and can happen only in DuckDB APIs that make use of a [database instance cache](/documentation/key-tasks/authenticating-and-connecting-to-motherduck/connecting-to-motherduck.md#multiple-connections-and-the-database-instance-cache).
In file-based DuckDB, this can only happen when the previous connection is still in scope.
With MotherDuck, the database instance cache is longer lived, so you may see this error even after the previous connections have been closed.

#### How to recover

For multiple connections that are used sequentially:
* If the configuration does not need to differ, consider unifying it, which will allow the same underlying client-side database instance to be reused.
* If the configuration differs intentionally, [set the database instance TTL to zero](/documentation/key-tasks/authenticating-and-connecting-to-motherduck/connecting-to-motherduck.md#setting-custom-database-instance-cache-time-ttl) and close the previous connections.

For multiple connections whose life cycles need to overlap, add a differentiating suffix to the connection string, so that these connections are no longer considered to be backed by the same database.
A good differentiating string is the [`session_name`](/key-tasks/authenticating-and-connecting-to-motherduck/connecting-to-motherduck/#session-names).
While it is meant to associate an individual end user to a dedicated backend when used with read scaling tokens, it can also be used to signal client-side intent for a distinct database instance when used with regular tokens.

---

Source: https://motherduck.com/docs/troubleshooting/faq

# FAQ
> Frequently asked questions about MotherDuck including DuckDB versions, connection methods, and common issues.
### What's the difference between .open md: & ATTACH 'md:' ?

`.open` initiates a new database connection (to a given database or `my_db` by default) and can be passed different parameters in the connection strings like `motherduck_token` or [saas_mode](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/authenticating-to-motherduck.md#authentication-using-saas-mode) flag. If you have previous local database attached, it will be detached when using `.open`.
`ATTACH` keeps the current database connection and attaches a new motherduck (cloud) database(s) to the current connection. You'll need to use `USE` to select the database you want to query.

### How do I know which version of DuckDB I should be running ?

MotherDuck supports DuckDB 1.5.3.
 - In **US East (N. Virginia) -** `us-east-1`, MotherDuck is compatible with client versions 1.4.0 through 1.5.3.
 - In **US West (Oregon) -** `us-west-2`, MotherDuck is compatible with client versions 1.4.1 through 1.5.3.
 - In **Europe (Frankfurt) -** `eu-central-1`, MotherDuck is compatible with client versions 1.4.1 through 1.5.3.

Please check that you have a compatible version of DuckDB running locally.

### How do I know which version of DuckDB am I running?

You can use the `VERSION` pragma to find out which version of DuckDB you are running

```sql
PRAGMA VERSION;
```

### How do I know what's executed locally and what's executed remote ?

If you run an [EXPLAIN](/sql-reference/motherduck-sql-reference/explain/) on your query, you will see the physical plan. Each operation is followed by either (L)= Local or (R)= Remote as shown in the query plan example below. More information can be found in the [documentation](/sql-reference/motherduck-sql-reference/explain/).

```sql
EXPLAIN [Your Query]
```

![explain-sample](./img/explain_sample.png)

### I connect to both MotherDuck and a local database, why is there an uncheckpointed WAL left behind?

DuckDB keeps a [database instance cache](/documentation/key-tasks/authenticating-and-connecting-to-motherduck/connecting-to-motherduck.md#multiple-connections-and-the-database-instance-cache) for each unique connection path.
Connecting to MotherDuck extends the lifetime of the database instance to a default of 15 minutes.
If you observe a WAL file left behind for the local database after the process exits or run into the "File is already open" error when closing and reopening the connection, there are several workarounds:

* Run `CHECKPOINT "local-database-name"` in the application code.
* Run `DETACH "local-database-name"` in the application code
* Disable the cache lifetime extension by setting `motherduck_dbinstance_inactivity_ttl` setting to `0s` (see [Setting Custom Database Instance Cache TTL](/documentation/key-tasks/authenticating-and-connecting-to-motherduck/connecting-to-motherduck.md#setting-custom-database-instance-cache-time-ttl)).

### Why am I not in the same Organization as my team?

If you sign up to MotherDuck directly, you will create your own Organization as a part of the sign up flow.
To join your team's Organization, reach out to your team and request that they [invite you to their Organization](../key-tasks/managing-organizations/managing-organizations.mdx#inviting-users-to-your-organization).
As an alternative, you may reach out to [MotherDuck support](./support.md) and we can search for other users within your domain.

### How do I use my team's shared databases?

Some database shares are scoped at the `ORGANIZATION` level. To use those shares, you must be in the same Organization as the person who created the share.
In addition, some shares are marked as 'DISCOVERABLE`. This allows members of the same Organization to find those shares through the UI.
Follow the steps outlined in ["Why am I not in the same Organization as my team?"](#why-am-i-not-in-the-same-organization-as-my-team) to join your team!

### How do I delete my account?

You can delete your account and all associated information by following these steps:

1. Navigate to your personal Settings and select "Members" from the left sidebar
2. Click the three dots (⋮) next to your name
3. Select "Delete"
4. Confirm the account deletion

:::note
If you are the only member of your Organization, deleting your account will also delete the Organization.
:::

For additional assistance, please contact our [support team](./support.md).

### Why I am getting SSL errors when connecting to MotherDuck from a Docker image?

If you see SSL errors when trying to connect to MotherDuck from a Docker image, this is likely because the image does not have updated CA certificates. If the container was working and suddenly stopped, it is likely that the certificates in the image have expired. Please refer to [Docker's documentation](https://docs.docker.com/engine/network/ca-certs/) for best practices on updating CA certificates in Docker images.

Some common errors you might see indicating an issue with your CA certificates include:

* `Could not get default pem root certs.`
* `Failed to create security handshaker.`
* `Update handshaker factory failed.`

### Why don't COPY DATABASE statements work in the MotherDuck Web UI?

The MotherDuck Web UI has limitations with certain SQL statements that are implemented as multiple statement macros:

**COPY DATABASE statements** have limited support in the MotherDuck Web UI:

* The full `COPY FROM DATABASE` command is not supported when copying both schema and data simultaneously
* **Workaround**: Use the `COPY FROM DATABASE` command with specific options:
  * `COPY FROM DATABASE source_db TO target_db (SCHEMA)` - copies only the database structure
  * `COPY FROM DATABASE source_db TO target_db (DATA)` - copies only the database data

For full functionality with these commands, use the DuckDB CLI or other supported drivers. More information about database copying can be found in the [database operations documentation](/documentation/key-tasks/database-operations/copying-databases.md).

---

Source: https://motherduck.com/docs/troubleshooting/uninstall

# Uninstall the MotherDuck extension
> Steps to completely remove the MotherDuck extension and related environment variables from your system.
### How do I uninstall MotherDuck?

* Remove `motherduck_*` from your environment variables (most likely only `motherduck_token`) [1]
* Remove any `motherduck*.duckdb_extension` file located into `~/.duckdb` [2]

[1] To view all your environment variables you may use:

```bash
$ env | grep -i motherduck
```

To unset in the current session:

```bash
$ unset motherduck_token
```

To unset the variable permanently, you may have to check your shell initialization files (`~/.bashrc`, `~/.zshrc`, etc.)

[2] Note those files are generally under `~/.duckdb/extensions/<DuckDB Version>/<platform>`. Eg. `~/.duckdb/extensions/v0.9.1/osx_arm64`.

You may use this script:

```bash
$ find ~/.duckdb -name 'motherduck*.duckdb_extension' -exec rm {} \;
```

---

Source: https://motherduck.com/docs/troubleshooting/reinstall-md-extension

# Reinstall the MotherDuck extension
> Force reinstall the MotherDuck extension when experiencing connection or compatibility issues.
The MotherDuck extension is automatically loaded and downloaded when you connect to MotherDuck. However, you can force a reinstallation by following these steps:

```sql
FORCE INSTALL motherduck;
```

Next to that make sure you are running the current supported [version of DuckDB](../faq#how-do-i-know-which-version-of-duckdb-i-should-be-running-).

---

Source: https://motherduck.com/docs/troubleshooting/windows-certs

# Install Let's Encrypt certificates on Windows
> Fix Let's Encrypt certificate trust issues on Windows that cause HTTP 400/500 connection errors.
In some circumstances, you may face an error that reads like `Http response at 400 or 500 level, http status code: 0`.
On Windows machine, this is usually due to [Let's Encrypt](https://letsencrypt.org/) certificate not being trusted.

To fix this, please follow the steps below:

* download this file https://letsencrypt.org/certs/isrgrootx1.der
* open it (double click on the file)

![Certificate window](images/open-certificate.png)
* click on "Install Certificate" and follow the instructions:

![Import certificate](images/certificate-import.png)

Then you should be able to try again.

If it still doesn't work, could you check if it was correctly installed by opening the certmgr (typing "`cert`" in the search box should show it)

![Manage user certificates](images/manage-user-certs.png)

And then it should be under `Trusted Root Certification Authorities\Certificates`:
![Certificates manager](images/certmgr.png)

---

Source: https://motherduck.com/docs/troubleshooting/aws-s3-secrets

# Troubleshoot AWS S3 secrets


> Diagnose and fix AWS S3 credential issues including IAM policies, credential chains, and secret configuration.

This page is for troubleshooting help with AWS S3 secrets in MotherDuck. For more information on creating a secret, see: [Create Secret](/documentation/sql-reference/motherduck-sql-reference/create-secret.md).

## Prerequisites

Before troubleshooting AWS S3 secrets, ensure you have:
- **Required**: [A valid MotherDuck Token](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/authenticating-to-motherduck.md#creating-an-access-token) with access to the target database
- **Required**: [AWS credentials](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html) (access keys, SSO, or IAM role)
- **Optional**: [DuckDB](https://duckdb.org/docs/stable/clients/cli/overview.html) CLI (for troubleshooting purposes, though any DuckDB client will work)
- **Optional**: [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) (for bucket access verification)

:::note
**AWS CLI PATH**: If you installed AWS CLI manually, you may need to add it to your system PATH. Package managers like Homebrew (macOS) typically add it to PATH automatically. Verify with `which aws` (macOS/Linux) or `where aws` (Windows) - if it returns a path, you're all set!
:::

## Verify secret access

### Check that the secret is configured

First, make sure you're connected to MotherDuck:

```sql
-- Connect to MotherDuck (replace 'your_db' with your database name)
ATTACH 'md:your_db';
```

Then type in the following:

```sql
.mode line
SELECT secret_string, storage FROM duckdb_secrets();
```

The output should look something like this. Verify that the output string includes values for: `key_id`, `region`, and `session_token`:

```text
secret_string = name=aws_sso;type=s3;provider=credential_chain;serializable=true;scope=s3://,s3n://,s3a://;endpoint=s3.amazonaws.com;key_id=<your_key_id>;region=us-east-1;secret=<your_secret>;session_token=<your_session_token>
```

:::note
If you see no results, it means no secrets are configured. You'll need to create a secret first using [CREATE SECRET](/documentation/sql-reference/motherduck-sql-reference/create-secret.md).
:::

If your output is missing a value for `key_id`, `region`, or `session_token`, you can recreate your secret by following the directions for [CREATE OR REPLACE SECRET](/documentation/sql-reference/motherduck-sql-reference/create-secret.md).

If that output worked successfully, you can confirm you have access to your AWS bucket by running these commands **in your terminal** (not in DuckDB):

```bash
# Log into AWS by running:
aws sso login

# Check bucket access:
aws s3 ls <your_bucket_name>
```

**Example Output:**

```text
PRE lambda-deployments/
PRE raw/
PRE ducklake/
2025-05-29 07:03:26   14695690 sample-data.csv
```

:::note
**Understanding the output**: `PRE` indicates folders/prefixes, while files show their size and modification date. If you only see `PRE` entries, your bucket contains organized data in folders. To explore deeper, use `aws s3 ls s3://<bucket-name>/<folder-name>/` or `aws s3 ls s3://<bucket-name>/ --recursive` to see all files.
:::

## Configure permissions in AWS

This is an example of an IAM policy that will allow MotherDuck to access your S3 bucket. Note: if you use KMS keys, the IAM policy should also have `kms:Decrypt` in `AllowBucketListingAndLocation`.

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowBucketListingAndLocation",
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation"
            ],
            "Resource": [
                "arn:aws:s3:::your_bucket_name"
            ]
        },
        {
            "Sid": "AllowObjectRead",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject"
            ],
            "Resource": [
                "arn:aws:s3:::your_bucket_name/*"
            ]
        }
    ]
}
```

## AWS credential chain

MotherDuck automatically finds your AWS credentials using AWS's credential chain. This is the recommended approach, as it uses short-lived credentials (typically valid for 1 hour), which are more secure and reduce the risk of credential leakage. For most users, it works seamlessly with your existing AWS setup.

### Most common: AWS SSO
If you use AWS SSO, first set up an SSO profile (if you haven't already):

```bash
aws configure sso
```

Then refresh your SSO token:

```bash
aws sso login --profile <your_sso_profile>
```

Create a secret using the `sso` chain with your profile name:

```sql
CREATE OR REPLACE SECRET my_secret IN MOTHERDUCK (
    TYPE s3,
    PROVIDER credential_chain,
    CHAIN 'sso',
    PROFILE '<your_sso_profile>'
);
```

:::note Secret validation
Starting with DuckDB v1.4.0, credentials are validated at secret creation time. If your credentials are not resolvable locally (for example, expired SSO tokens or missing `~/.aws/credentials`), the `CREATE SECRET` command will fail with a `Secret Validation Failure` error. The recommended fix is to use the correct `CHAIN` and `PROFILE` for your credential type (see the SSO example above) and confirm your SSO session is active. If you need to bypass local validation, you can add `VALIDATION 'none'`, but keep in mind that this skips the local check that confirms your credentials are valid before storing them in MotherDuck.
:::

### Other credential types
The credential chain also works with:
- **Access keys** stored in `~/.aws/credentials`
- **IAM roles** (if running on EC2)
- **Environment variables**

### Advanced: role assumption
:::note
**Only needed for**: Cross-account access, elevated permissions, or when you need to assume a different role than your current profile.
:::

If you need to assume a specific IAM role, create a profile in `~/.aws/config`:

```ini
[profile my_motherduck_role]
role_arn = arn:aws:iam::your_account_id:role/your_role_name
source_profile = your_source_profile
```

Then create a secret that uses this profile:

```sql
CREATE SECRET my_s3_secret (
    TYPE S3,
    PROVIDER credential_chain,
    PROFILE 'my_motherduck_role',
    REGION 'us-east-1' -- Use your bucket's region if different
);
```

## Common challenges

### Scope

When using multiple secrets, the `SCOPE` parameter ensures MotherDuck knows which secret to use. You can validate which secret is being used with the `which_secret` function:

```sql
SELECT * FROM which_secret('s3://my-bucket/file.parquet', 's3');
```

### Periods in bucket name (url_style = path)

Because of SSL certificate verification requirements, S3 bucket names that contain dots (.) cannot be accessed using virtual-hosted style URLs. This is due to AWS's SSL wildcard certificate (`*.s3.amazonaws.com`) which only validates single-level subdomains.

If your bucket name contains dots, you have two options:

1. **Rename your bucket** to remove dots (e.g., use dashes instead)
2. **Use path-style URLs** by adding the `URL_STYLE 'path'` option to your secret:

```sql
CREATE OR REPLACE SECRET my_secret (
    TYPE s3,
    URL_STYLE 'path',
    SCOPE 's3://my.bucket.with.dots'
);
```

For more information, see [Amazon S3 Virtual Hosting documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html).

## What's Next

After resolving your AWS S3 secret issues:

- **[Query your S3 data](/key-tasks/cloud-storage/querying-s3-files.md)** - Learn how to query files stored in S3
- **[Load data into MotherDuck](/key-tasks/loading-data-into-motherduck/)** - Set up data loading workflows
- **[Configure additional cloud storage](/integrations/cloud-storage/)** - Set up Azure, Google Cloud, or other providers
- **[Share data with your team](/key-tasks/sharing-data/)** - Collaborate using MotherDuck's sharing features

---

Source: https://motherduck.com/docs/troubleshooting/troubleshooting-access-policy

# Data access policy for support troubleshooting
> Policy details for when MotherDuck support accesses your account data during troubleshooting.
To help you with certain kinds of MotherDuck issues, it can be helpful for us to access your MotherDuck account. For example, if a specific query on a specific dataset is triggering a bug, it may be necessary for us to access the data and SQL query, and possibly re-run a specific query, to reproduce the issue and diagnose the problem.

A MotherDuck employee may use our community Slack or
email to request your permission to access your MotherDuck account while troubleshooting an issue.
If you give us permission to access to your MotherDuck account for troubleshooting, here is what you need to know:

- Our goal is to understand the issue and resolve the problem. We will make every effort to minimize the amount of time we spend accessing your account and the amount of data we access. We will only access the data we need to investigate and troubleshoot the specific issue.
- Any access to your data will be strictly read-only.
- A MotherDuck employee may pull in other MotherDuck employees during the debugging process. By agreeing to allow us to access your account for troubleshooting an issue, other MotherDuck employees who are asked to help investigate the issue may also access your account, subject to the same terms of this policy, without requesting additional authorization from you.
- We will not share or disclose the data we access while troubleshooting the issue to any third party or non-MotherDuck employee.
- We may make temporary copies of your data while debugging the issue. Any such copies will be permanently deleted once the issue is resolved.
- We may use the data we access in your account to generate a redacted copy of the data to be used for creating a bug report or test.
- The permission you have granted to access your account lapses once this specific issue is resolved.

---

Source: https://motherduck.com/docs/troubleshooting/support

# Contact support
> Contact MotherDuck support via Slack community or email for questions not covered in the FAQ.
Have a question that isn't answered in our [FAQ](./faq.md)? Join the [MotherDuck Slack Community](https://slack.motherduck.com/) or contact us at [support@motherduck.com](mailto:support@motherduck.com?subject=Support+question).

---

Source: https://motherduck.com/docs/troubleshooting/version-lifecycle-schedules

# MotherDuck version lifecycle schedules
> DuckDB and DuckLake version support schedules, end of life policies, and extended lifecycle support options.
MotherDuck supports DuckDB versions according to a predictable lifecycle so you always know which version is safe to use.

The lifecycle schedules below form a part of MotherDuck’s Support Policies. They include Major Releases and Minor Releases to support [DuckDB](/troubleshooting/faq/#how-do-i-know-which-version-of-duckdb-i-should-be-running-) and [DuckLake](/integrations/file-formats/ducklake/) versions and specify end of life dates for both.

## Supported versions

MotherDuck supports DuckDB 1.5.3.
 - In **US East (N. Virginia) -** `us-east-1`, MotherDuck is compatible with client versions 1.4.0 through 1.5.3.
 - In **US West (Oregon) -** `us-west-2`, MotherDuck is compatible with client versions 1.4.1 through 1.5.3.
 - In **Europe (Frankfurt) -** `eu-central-1`, MotherDuck is compatible with client versions 1.4.1 through 1.5.3.

MotherDuck strives to support DuckDB Major and Minor versions in alignment with the [DuckDB](https://duckdb.org/release_calendar) and [DuckLake](https://ducklake.select/release_calendar) release calendars.

For new releases, MotherDuck provides updates to users through email and the [Community Slack](https://slack.motherduck.com/) if support for new versions will take more than 48 hours. Newly supported versions are announced in our [release notes](https://motherduck.com/docs/about-motherduck/release-notes/).

When a version is available, we recommend that users [install and run the latest **MotherDuck-supported version**](https://motherduck.com/docs/getting-started/interfaces/connect-query-from-duckdb-cli/#install-with-bash) to take advantage of the most up-to-date features and functionality.

## Programmatic access

Agents, scripts, and CI checks can read the supported version ranges as JSON:

```bash
curl https://motherduck.com/docs/duckdb-versions.json
```

Response shape:

```json
{
  "title": "MotherDuck supported DuckDB versions",
  "description": "Versions of DuckDB and DuckDB-based language clients supported by MotherDuck...",
  "$comment": "https://motherduck.com/docs/troubleshooting/version-lifecycle-schedules/",
  "duckdb": {
    "motherduck_regions": {
      "global":       { "min": "1.4.0", "max": "1.5.3" },
      "us-east-1":    { "min": "1.4.0", "max": "1.5.3" },
      "us-west-2":    { "min": "1.4.1", "max": "1.5.3" },
      "eu-central-1": { "min": "1.4.1", "max": "1.5.3" }
    }
  },
  "language_clients": {
    "duckdb_jdbc": "1.5.1.0"
  }
}
```

How to read it:

- `duckdb.motherduck_regions.<region>` is the inclusive `min`/`max` DuckDB version range that the named MotherDuck region accepts. Use this as the default compatibility window for any client.
- `language_clients` lists individually-published drivers with a fixed published version. For any client not listed here (Python, Node.js, Go, and so on), use the matching region's range from `duckdb.motherduck_regions`.

The JSON updates whenever the support windows on this page change — the version numbers above and the `<Versions>` components throughout the docs render from the same file.

### Updating the data (for MotherDuck contributors)

The source of truth is `static/duckdb-versions.json` in the [`motherduck-docs`](https://github.com/motherduckdb/motherduck-docs) repository. Update this file when:

- A new DuckDB version is qualified for MotherDuck (bump `max` for each entry under `duckdb.motherduck_regions`).
- A previous DuckDB version reaches End of Life and is removed from support (bump `min` for each entry under `duckdb.motherduck_regions`).
- The published JDBC driver version changes (update `language_clients.duckdb_jdbc`).

The same file feeds the `<Versions>` and `<DownloadLink>` components rendered throughout these docs, so a single edit propagates everywhere.

## MotherDuck support lifecycle schedules

The chart shows current support windows. The tables list all versions.

### Chart View

    ```mermaid
    %%{init: {
      "theme": "base",
      "themeVariables": {
        "fontFamily": "var(--ifm-font-family-base)",
        "textColor": "#383838",
        "titleColor": "#383838",
        "primaryColor": "#16AA98",
        "primaryTextColor": "#383838",
        "primaryBorderColor": "#383838",
        "sectionBkgColor": "#F4EFEA",
        "sectionBkgColor2": "#F4EFEA",
        "altSectionBkgColor": "#F4EFEA",
        "gridColor": "#B8C3CA",
        "taskBkgColor": "#16AA98",
        "taskBorderColor": "#383838",
        "activeTaskBkgColor": "#16AA98",
        "activeTaskBorderColor": "#0C7D71",
        "doneTaskBkgColor": "#D7D7D7",
        "doneTaskBorderColor": "#8C8C8C",
        "critBkgColor": "#16AA98",
        "critBorderColor": "#0C7D71",
        "todayLineColor": "#FFDE02",
        "taskTextColor": "#383838",
        "taskTextDarkColor": "#383838",
        "taskTextOutsideColor": "#383838"
      },
      "gantt": {
        "fontSize": 16,
        "sectionFontSize": 18,
        "barHeight": 30,
        "barGap": 14,
        "leftPadding": 116,
        "topPadding": 42,
        "gridLineStartPadding": 36
      }
    }}%%
    gantt
        dateFormat YYYY-MM-DD
        axisFormat %b '%y
        tickInterval 1month
        todayMarker stroke-width:3px,stroke:#FFDE02,opacity:0.9

        section DuckDB
        DuckDB 1.4.x LTS :active, 2025-10-09, 2026-09-30
        DuckDB 1.5.1 :active, 2026-03-24, 2027-03-31
        DuckDB 1.5.2 :active, 2026-04-13, 2027-03-31
        DuckDB 1.5.3 :crit, 2026-05-20, 2027-03-31

        section DuckLake
        DuckLake 0.4 :active, 2026-03-24, 2026-09-30
        DuckLake 1.0 :crit, 2026-04-13, 2027-03-31
    ```

### Table View

    The chart uses MotherDuck support announcement dates where available. The tables below retain version release dates and support end dates.

    **DuckDB support schedule**

    | DuckDB release | Supported DuckLake version (release date) | Release date | End of life date* |
    |----------------|-------------------------------------------|--------------|-------------------|
    | 1.5.3          | 1.0 (April 13, 2026)                      | May 20, 2026 | March 2027      |
    | 1.5.2          | 1.0 (April 13, 2026)                      | April 13, 2026 | March 2027    |
    | 1.5.1          | 0.4 (March 9, 2026)                       | March 23, 2026 | March 2027    |
    | 1.5.0          | 0.4 (March 9, 2026)                       | March 9, 2026 | March 2027     |
    | 1.4.4          | 0.3 (September 17, 2025)                  | January 27, 2026 | September 2026 |
    | 1.4.3          | 0.3 (September 17, 2025)                  | December 9, 2025 | September 2026 |
    | 1.4.2          | 0.3 (September 17, 2025)                  | November 12, 2025 | September 2026 |
    | 1.4.1          | 0.3 (September 17, 2025)                  | October 7, 2025 | September 2026 |
    | 1.4.0          | 0.3 (September 17, 2025)                  | September 16, 2025 | September 2026 |
    | 1.3.2          | —                                         | July 8, 2025 | March 2026       |
    | 1.3.1          | —                                         | June 16, 2025 | March 2026       |
    | 1.3.0          | —                                         | May 21, 2025 | March 2026       |
    | 1.2.2          | —                                         | April 8, 2025 | January 2026     |
    | 1.2.1          | —                                         | March 5, 2025 | January 2026     |
    | 1.2.0          | —                                         | February 5, 2025 | January 2026   |
    | 1.1.3          | —                                         | November 4, 2024 | July 2025      |
    | 1.1.2          | —                                         | October 14, 2024 | July 2025      |
    | 1.1.1          | —                                         | September 24, 2024 | July 2025    |
    | 1.1.0          | —                                         | September 9, 2024 | July 2025     |
    | 1.0.0          | —                                         | June 3, 2024 | July 2025         |

    * Beginning with DuckDB 1.3.0, MotherDuck supports each Minor Release until the date specified above.

    **DuckLake support schedule**

    | DuckLake release | Supported DuckDB version (release date) | Release date | End of life date** |
    |------------------|-----------------------------------------|--------------|--------------------|
    | 1.0              | 1.5.2-1.5.3 (April-May 2026)            | April 13, 2026 | January 2027     |
    | 0.4              | 1.5.0-1.5.1 (March 2026)                | March 9, 2026 | September 2026    |
    | 0.3              | 1.4.x (September 2025-January 2026)     | September 17, 2025 | March 2026    |
    | 0.2              | 1.3.x (May-July 2025)                   | July 4, 2025 | September 2025     |
    | 0.1              | 1.3.x (May-July 2025)                   | May 27, 2025 | July 2025          |

        **Note:** DuckLake 1.0 support is aligned with the DuckDB 1.5.x support window shown above.

## End of life (EOL) policy

When a new Minor version becomes available, the previous one enters Extended Support. While we don't offer support for new features, critical fixes may still be backported for the greater of:
 - **6 months** after the version’s release, or
 - **4 months** after the next Minor version is released

When a Minor version reaches its End of Life (EoL):
 - Connections using that DuckDB version are blocked, requiring MotherDuck users to upgrade
 - Ahead of scheduled End of Life (EoL) dates, MotherDuck provides in-app UI warnings, email communications, and targeted outreach to users about impacted versions slated for deprecation

DuckLake versions follow the published compatibility schedule above and require a supported DuckDB and DuckLake combination.

## MotherDuck extended lifecycle support add-on

MotherDuck offers an **Extended Lifecycle Support Add-On** to provide customers with peace of mind and flexibility to upgrade at a later date by extending ongoing technical support for a Minor DuckDB version after it reaches its End of Life (EOL) date.

For more information, please [get in touch with our team](https://motherduck.com/contact-us/product-expert/).

💁 If you have additional questions about our version lifecycle, feel free to connect with us directly in our [Community Slack support channel](https://slack.motherduck.com/) or send a note to support@motherduck.com.

---

Source: https://motherduck.com/docs/troubleshooting/glossary

# Glossary
> Definitions of key terms and concepts used throughout the MotherDuck documentation.
## MotherDuck architecture

| Term | Definition |
|------|------------|
| duckling | A dedicated DuckDB compute instance provisioned for each user or service account. Each duckling has its own CPU, memory, and fast SSD spill space. [Learn more](/docs/concepts/hypertenancy/). |
| flight | A Python program that MotherDuck schedules and runs with direct access to your databases. Each run gets an isolated Python runtime, used for ingest, transforms, reverse ETL, and other work that doesn't fit a single SQL query. [Learn more](/docs/concepts/flights/). |
| hypertenancy | MotherDuck's tenancy model where every user gets their own dedicated DuckDB compute instance (duckling), providing full compute isolation and eliminating noisy-neighbor problems. [Learn more](/docs/concepts/hypertenancy/). |
| noisy neighbor | A problem in shared-resource systems where one user's heavy workload degrades performance for others. MotherDuck's hypertenancy model eliminates this. |
| service account | A non-human user account for powering applications, pipelines, or services. Service accounts have their own tokens and duckling sizes, separate from interactive users. [Learn more](/docs/key-tasks/service-accounts-guide/). |
| SSD | Solid-state drive: fast local storage attached to each duckling, used as spill space when a query exceeds available memory. |

## Query execution

| Term | Definition |
|------|------------|
| dual execution | A query execution model that automatically routes stages of a query to the most efficient location, whether local (your machine) or cloud (MotherDuck), based on where the data lives. [Learn more](/docs/key-tasks/running-hybrid-queries/). |
| hybrid query | A query that accesses both local DuckDB databases and MotherDuck cloud databases in a single SQL statement. [Learn more](/docs/key-tasks/running-hybrid-queries/). |
| vectorized execution | A query processing technique that operates on batches of values at once rather than row-by-row, improving CPU cache utilization and query speed. |

## Data management

| Term | Definition |
|------|------------|
| checkpoint | An operation where the current database state is written to persistent storage, creating a recoverable point and making changes visible to read-scaling replicas and shares. |
| fully qualified name | A reference to a database object that includes all parent namespaces, written as database.schema.table (or database.schema.view). Useful for disambiguating objects across attached databases and required when views or queries need to resolve tables across databases. [Learn more](/docs/key-tasks/database-operations/specifying-different-databases/). |
| MotherDuck share | A zero-copy, read-only database object that lets you share data with other MotherDuck users or across your organization without duplicating storage. [Learn more](/docs/key-tasks/sharing-data/sharing-overview/). |
| read scaling | A feature that spins up additional read-only duckling replicas to handle read-heavy workloads. Queries are distributed across replicas with eventual consistency (syncing within minutes). [Learn more](/docs/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/). |
| snapshot | An immutable point-in-time copy of a database. Automatic snapshots enable time travel and data recovery; named snapshots persist until explicitly dropped. [Learn more](/docs/concepts/data-recovery/). |
| time travel | The ability to query a database as it existed at a previous point in time using snapshots, useful for data recovery and auditing. [Learn more](/docs/key-tasks/database-operations/time-travel/). |
| transient database | A MotherDuck database type with shorter snapshot retention and no failsafe period, suited for temporary or ephemeral data. [Learn more](/docs/sql-reference/motherduck-sql-reference/create-database/). |
| zero-copy clone | A metadata-only operation that creates a new database reference sharing the same underlying data, consuming no additional storage. |

## Identity and access

| Term | Definition |
|------|------------|
| deprovisioning | Disabling a user's access while retaining their account record and data. In MotherDuck, deprovisioned users cannot sign in and their access tokens are revoked, but they can be reprovisioned later. [Learn more](/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/scim/). |
| IdP | Identity provider: a service that authenticates users and sends identity or provisioning information to applications, such as Okta, Microsoft Entra ID, Google Workspace, or Keycloak. |
| JIT provisioning | Just-in-time provisioning: automatic account creation when a user signs in successfully for the first time through SSO, instead of creating the account ahead of time. [Learn more](/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/sso-setup/#just-in-time-jit-user-provisioning). |
| OIDC | OpenID Connect: an identity layer on OAuth 2.0 used for browser-based authentication and single sign-on. [Learn more](/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/sso-setup/#saml-vs-oidc). |
| SAML | Security Assertion Markup Language: an XML-based protocol used by many enterprise identity providers for browser-based single sign-on. [Learn more](/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/sso-setup/#saml-vs-oidc). |
| SCIM | System for Cross-domain Identity Management: an open standard used to automate user provisioning, updates, deprovisioning, and deletion between an identity provider and an application. [Learn more](/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/scim/). |
| SSO | Single sign-on: an authentication setup where users sign in through a central identity provider instead of separate application-specific credentials. [Learn more](/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/sso-setup/). |

## Connection modes

| Term | Definition |
|------|------------|
| SaaS mode | A connection setting that sandboxes a MotherDuck session by blocking local file access, local DuckDB attachments, extension install or load, and most DuckDB configuration changes. Used automatically by the Postgres endpoint and recommended for third-party tools that host DuckDB. [Learn more](/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/#authentication-using-saas-mode). |
| single mode | A connection mode that creates a temporary, non-persistent session. Attachment changes are discarded when you disconnect. Useful for BI tools and ephemeral workloads. [Learn more](/docs/key-tasks/authenticating-and-connecting-to-motherduck/attach-modes/). |
| workspace mode | The default connection mode where database attachment changes persist across sessions. All databases from your last session are automatically restored. [Learn more](/docs/key-tasks/authenticating-and-connecting-to-motherduck/attach-modes/). |

## Storage and formats

| Term | Definition |
|------|------------|
| columnar storage | A data layout that stores each column separately rather than row-by-row, enabling better compression and faster analytical queries that read only the columns they need. |
| DuckLake | An open table format that stores metadata in database tables rather than files, enabling faster metadata lookups and multi-table ACID transactions on data in object storage. [Learn more](/docs/concepts/ducklake/). |
| object storage | Scalable cloud storage (like S3, GCS, or Azure Blob Storage) that stores data as objects, commonly used for data lakes. |
| OLAP | Online Analytical Processing: a category of database systems optimized for complex queries across large datasets, as opposed to OLTP systems designed for frequent small transactions. |
| Parquet | An open columnar file format optimized for analytical workloads, providing efficient compression and fast reads for specific columns. |

---

Source: https://motherduck.com/docs/troubleshooting/troubleshooting

# Troubleshooting
> Troubleshooting