dotnet test "Settings file not found" - Bad .runsettings in CI

A dotnet test --settings <file>.runsettings pointed at a runsettings file that is missing on the runner, or the file is malformed. The test run aborts before any test executes.

What this error means

dotnet test fails immediately saying the settings file could not be found (or that the runsettings is invalid), and no tests run. It happens when the --settings path is wrong for the runner’s working directory, or the file was not checked out.

dotnet test output

The Settings file '/home/runner/work/app/ci.runsettings' could not be found.

Common causes

Wrong or non-existent runsettings path

The path passed to --settings is relative to a different directory than the step runs in, or the file is simply not present on the runner.

Malformed runsettings XML

An invalid .runsettings (bad XML, unknown elements) is rejected, so the test run cannot start even though the file exists.

How to fix it

Pass a correct repo-relative path

Point --settings at the actual file and confirm it exists first.

Terminal

ls ./tests/ci.runsettings
dotnet test --settings ./tests/ci.runsettings

Validate the runsettings content

Keep the runsettings well-formed and minimal so it is accepted.

ci.runsettings

<?xml version="1.0" encoding="utf-8"?>
<RunSettings>
  <RunConfiguration>
    <TargetFrameworks>net8.0</TargetFrameworks>
  </RunConfiguration>
</RunSettings>

How to prevent it

Reference .runsettings by an explicit repo-relative path that exists in the checkout.
Set the step working-directory so relative settings paths resolve predictably.
Keep runsettings XML well-formed; validate it in CI if it changes often.