# Environments

Source: https://docs.qualflare.com/docs/runs/environments · Last updated: 2026-10-27

Environments in Qualflare label where tests ran. Every project starts with development, staging, production and qa; uploads must name an existing identifier.

In Qualflare, an [environment](https://docs.qualflare.com/docs/reference/glossary#environment) labels where tests ran, such as `staging`; every new project starts with four, `development`, `staging`, `production` and `qa`, and every launch belongs to exactly one.

This page lists every field, default and rule of environments, and how the app and the CLI use them.

| Fact              | Detail                                                                                                                                                                                                                              |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Where             | **Settings** > **Environments** in the project sidebar                                                                                                                                                                              |
| Create and delete | (requires the Editor role or higher in the project). In the web app today, buttons follow your project role ([Roles and permissions](https://docs.qualflare.com/docs/administration/roles-permissions#workspace-and-project-roles)) |
| Defaults          | `development`, `staging`, `production` and `qa`                                                                                                                                                                                     |
| CLI               | `--environment` / `-e` or `QF_ENVIRONMENT`; default `development` ([order](https://docs.qualflare.com/docs/runs/environments#use-environments-from-the-cli))                                                                |
| Edit              | No edit action in the app                                                                                                                                                                                                           |
| Delete            | Only while no launch uses it                                                                                                                                                                                                        |

*Figure: Every new project starts with these four environments.*

## Why environments are separate from launches

A launch is a single test run. An environment is a label that many launches share. Separating the two means:

* The same suite can run against staging today and production tomorrow, and you can compare the results.
* The **Launches** list and the **Overview** page can be filtered by environment.
* Each launch keeps the environment it ran in.

## Environment fields

Each environment has three text fields. The form needs at least 3 characters in each.

### Identifier

The value the CLI and API use, for example `staging`, up to 100 characters. It is unique within the project and case-sensitive: `Production` and `production` are different identifiers. You can't change it in the app.

### Name

The display name the app shows, for example Staging, up to 100 characters.

### Description

A short note about the environment, up to 256 characters.

Environments have no base URL, variables, secrets, headers, authentication, type, status or default flag, so **Start Launch** asks you to pick one every time.

## Default environments

Every new project starts with four environments:

| Identifier    | Name        |
| ------------- | ----------- |
| `development` | Development |
| `staging`     | Staging     |
| `production`  | Production  |
| `qa`          | QA          |

`qf <identifier> collect` uses `development` when you don't choose an environment.

## Where environments appear

Environments appear wherever you filter or compare results:

* **Launches**: the **Environment** column and filter, and a chip in the launch header ([Filters](https://docs.qualflare.com/docs/runs/launches#filters))
* **Overview**: the **Environment** filter and the **Success Rate by Environment** chart ([Overview dashboard](https://docs.qualflare.com/docs/analytics))
* **Defects**: the **Environment** field, column and filter ([Create, triage and close defects](https://docs.qualflare.com/docs/defects/manage-defects))
* **CLI**: `qf <identifier> launches list --environment <identifier>` ([Launches commands](https://docs.qualflare.com/docs/cli/read-commands#launches))

To type environment filters, see [Search, filters and shortcuts](https://docs.qualflare.com/docs/get-started/search-and-filters).

## Environment list

Open **Settings** > **Environments** in the project sidebar.

| Column           | Description                                    |
| ---------------- | ---------------------------------------------- |
| **Name**         | The display name, with the identifier under it |
| **Description**  | The environment's description                  |
| **Date Created** | When the environment was created               |
| **Date Updated** | When the environment last changed              |

Click **Name**, **Date Created** or **Date Updated** to sort. The list starts sorted by **Date Created**, newest first. Type in &#x2A;*Filter environments...** to filter the list by name.

## Create an environment

You need the Editor role or higher on the project to create or delete environments. In the web app today, buttons follow your project role.

1. Click **Create Environment**.
2. Enter an **Identifier**, a **Name** and a **Description**. The form needs at least 3 characters in each field. The identifier and the name can be up to 100 characters.
3. Click **Create**.

Use short, lowercase identifiers such as `staging` or `staging-eu`. They appear in CI commands, and you can't change them in the app.

*Figure: The identifier is what the CLI and the API use, and you can't change it in the app.*

## Edit an environment

The app has no edit action for environments. To use a different identifier, create a new environment. A launch's environment can't be changed after the launch exists.

## Delete an environment

> **Caution:** **Delete** runs at once. There is no confirmation and no undo.

1. Open the &#x2A;*⋯** menu on the environment's row.
2. Click **Delete**.

You can delete an environment only when no launch uses it. Otherwise Qualflare refuses and shows:

```text
environment "<identifier>" still has N launch(es); deleting it would permanently remove them and all of their results. Delete or reassign the launches first.
```

A launch's environment can't be changed, so the environment stays until every launch in it is deleted.

## Use environments from the CLI

`qf <identifier> collect` sends an environment identifier with every upload:

```bash
qf myapp collect results.xml --environment staging
```

The CLI picks the environment in this order:

1. The `--environment` (or `-e`) flag
2. The `QF_ENVIRONMENT` environment variable
3. The environment a Qualflare reporter wrote into its report file
4. `development`

The value must match an existing **Identifier**, not the Name. Matching is case-sensitive: `Production` and `production` are different identifiers. The `qf <identifier> collect --help` text calls the flag "Environment name", but it takes the identifier.

Qualflare doesn't create environments on upload. An unknown identifier is rejected with HTTP 400 and this message, and `qf` exits with code 1:

```text
environment "<identifier>" does not exist in this project
```

Create the environment in **Settings** > **Environments**, then upload again. See also [Environment mismatch](https://docs.qualflare.com/docs/cli/troubleshooting#environment-mismatch) and, for pipelines, [CI/CD](https://docs.qualflare.com/docs/cli/ci-cd).

## Use environments in manual runs

**Start Launch** asks you to pick an environment every time ([Start a launch from suites](https://docs.qualflare.com/docs/runs/manual-testing#starting-a-test-run)). With **Create Run** on a [test plan](https://docs.qualflare.com/docs/test-management/test-plans), you pick it in the Test Wizard before the first verdict ([Check the environment and language](https://docs.qualflare.com/docs/runs/manual-testing#configuring-the-run)). Either way, it can't be changed once the launch exists.

## Errors

| Message                                                     | When                                                                                      | Fix                                                                                                                                                                     |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `environment "<identifier>" does not exist in this project` | An upload names an identifier the project doesn't have (HTTP 400; `qf` exits with code 1) | Create the environment, then upload again. See [Use environments from the CLI](https://docs.qualflare.com/docs/runs/environments#use-environments-from-the-cli) |
| `environment "<identifier>" still has N launch(es)…`        | You delete an environment that launches use (HTTP 409)                                    | Delete every launch in it first. See [Delete an environment](https://docs.qualflare.com/docs/runs/environments#delete-an-environment)                           |
| `Select environment and language first`                     | You record a verdict in the Test Wizard before both are set                               | Set both above the case list. See [Use environments in manual runs](https://docs.qualflare.com/docs/runs/environments#use-environments-in-manual-runs)          |

## Limits

* Every field needs at least 3 characters; Identifier and Name take up to 100 characters, and Description up to 256. See [Environment fields](https://docs.qualflare.com/docs/runs/environments#what-an-environment-holds).

## Related

* **Guides:** [Run manual tests](https://docs.qualflare.com/docs/runs/manual-testing) · [Run tests: manual and automated](https://docs.qualflare.com/docs/runs)
* **Reference:** [Launches](https://docs.qualflare.com/docs/runs/launches) · [Projects](https://docs.qualflare.com/docs/administration/projects) · [Project settings](https://docs.qualflare.com/docs/administration/project-settings)
* **CLI:** [`--environment`](https://docs.qualflare.com/docs/cli/collect#flag-descriptions)