Troubleshooting

The problems below are the ones a new suite meets first. Each one starts with the message you see.

Messages to fix

Copy the quoted message and find it below. Each row names the meaning, the fix and the section that walks it in full.

What you see	What it means	Fix	Deep dive
CS0616: 'ProtoTest' is not an attribute class	[ProtoTest] resolved to the ProtoTest namespace because the adapter's attribute is not in scope	add using ProtoTest.NUnit;, or the adapter package for your runner. The runner pages list the usings.	I see ProtoHost is not initialized
NU1605: Detected package downgrade: NUnit from 4.6.1 to 4.3.2	dotnet new nunit pins NUnit 4.3.2 while ProtoTest.NUnit needs 4.6.1 or newer	bump NUnit first: dotnet add package NUnit --version 4.6.1. See Installation.	I see ProtoHost is not initialized
Aspire resource 'api' has no 'http' endpoint	the AppHost project resource declares no http endpoint: no WithHttpEndpoint, and no applicationUrl in its launch profile	declare the endpoint in the AppHost, or point UseEndpoint("api", "https") at one the resource exposes. See Aspire.	The application does not start in-process
Aspire resource 'api' has no value yet: the AppHost publishes 'ProtoTest:Applications:api:BaseUrl' when the run starts	the AppHost was never selected, usually because ProtoTest__Aspire__Enabled=true set in the shell never reached the host	add .AddEnvironmentVariables() to the suite's configuration sources. See Configuration.	I see No application is selected
No password has been provided	the code read the connection string from the opened connection, and opening strips credentials	read the value the run started from ProtoInfrastructureSettings.Values, password included. See SQL.	Containers do not start
prototest summary shows ? where a trace name uses ·	the terminal is not reading the CLI's UTF-8 output as UTF-8	the CLI sets UTF-8 output when it starts; if the console still substitutes glyphs, switch it to a UTF-8 code page (chcp 65001 on Windows) or use a UTF-8 terminal. See CLI reference.	The CI artifact is empty
ProtoHost is not initialized	the runner never ran the setup class	check the setup for your runner below	I see ProtoHost is not initialized
No active ProtoExecutionContext	Proto.Context was read outside a ProtoTest test	use the ProtoTest attribute, or pass the context along	I see No active ProtoExecutionContext
No application is selected or has no Rest client registered	the test names no client	select the application or name the client	I see No application is selected
Program is inaccessible or the in-process host fails	the application's entry point is internal, or its configuration is missing	add public partial class Program;, or feed the configuration from the test run	The application does not start in-process
Docker endpoint or container startup failure	Docker is not running or not reachable	start Docker, or give the suite a connection string instead	Containers do not start
Playwright cannot find a browser executable	the browser was never installed on the machine	set InstallBrowsers = true, or drive an installed browser by channel	The browser does not launch
Tests pass separately but fail in a full run	parallel tests share names or state	derive names from the test id	Tests pass alone and fail together
No .prototrace, report or CI artifact	the trace lands where the test process runs, not where CI looks	set an absolute PROTOTEST_RESULTS directory	Where is the trace? and The CI artifact is empty

The sections below walk each problem in full. ProtoTrace records every hook, request and check in order; open the trace when a message below does not explain what you see.

I see ProtoHost is not initialized

No active ProtoHost is available. The runner setup creates it: derive the suite's [SetUpFixture] from ProtoTestAssembly ...

The runner never ran your setup class, so no host was built. The rest of the message points at the fix, and the adapter's own hint (Ensure your setup class inherits from ProtoTestAssembly., Register your fixture with [assembly: AssemblyFixture(...)], ...) tells you which one. Check the one that applies to your runner:

• NUnit: the [SetUpFixture] only covers its own namespace and the namespaces below it. A test in Orders.Tests.Api is covered by a setup in Orders.Tests, not by one in Orders.Tests.Web. Move the setup up, or out of any namespace to cover the whole assembly.
• xUnit v3: [assembly: AssemblyFixture(typeof(Setup))] is missing.
• xUnit v2: the test class is not in the ProtoTest collection. Add [Collection(ProtoTestCollection.Name)].
• MSTest, TUnit: the assembly hooks do not call InitializeAsync, or the class holding them is not discovered (MSTest needs [TestClass] on it).

Each runner's page under Test runners shows the complete setup.

I see No active ProtoExecutionContext

No active ProtoExecutionContext is available on this flow. Proto.Context only works inside a test body ...

Proto.Context was read outside a ProtoTest test. Usually the test uses the runner's own attribute ([Test], [Fact], [TestMethod]) instead of the ProtoTest attribute that opens the context ([ProtoTest], or [ProtoTestFact] / [ProtoTestTheory] for xUnit). It also happens in code that runs outside the test's async flow, such as a static initializer or a thread started by hand. Pass the ProtoExecutionContext along, or, for telemetry that cannot take it, reach the owning test's trace with ProtoHost.FindTraceWriter(Activity?). Off test flows the message also names the alternatives.

I see No application is selected

No application is selected for this test. Apply [Application(name)] or pass a Rest client name to the accessor.

Proto.Context.Rest() without a name uses the selected application's client. Put [Application("Api")] on the class or the test, or ask for a client by name: Proto.Context.Rest("Api").

Application 'Api' has no Rest client registered. Register one in AddApplication or pass a client name to the accessor.

The application is composed without that protocol. Add it in the setup: .AddApplication("Api", app => app.AddRest(rest => rest.AddClient("Api"))).

No HTTP client 'Api' is registered. Register it under the application, back the application with AddAspNetCoreServer, or set 'ProtoTest:Applications:Api:BaseUrl'.

The client has nowhere to send requests. Either host the application in-process with AddAspNetCoreServer<Program>(), or point it at a running one with ProtoTest:Applications:Api:BaseUrl. See Configuration.

The application does not start in-process

• Program is inaccessible. A minimal-API application's entry point is internal. Add public partial class Program; to the application, as in Your first test.
• The application reads configuration the test run does not have. The in-process server runs the application's own Program, with its own appsettings.json. Values that come from the environment in production, such as connection strings and secrets, have to come from the test run: from infrastructure that fills them, or from configureWebHost on AddAspNetCoreServer.

Containers do not start

Infrastructure such as PostgresDatabase.Container() runs on Docker through Testcontainers. When Docker is not running or not reachable, the run fails before the first test, with Testcontainers' own message about the Docker endpoint.

• Start Docker Desktop, or on Linux make sure the current user can reach the Docker socket.
• On CI, use a runner image with Docker available.

Running where Docker is not available

Give the suite a connection string through configuration instead of a container. A test-level skip cannot get in front of it: AddInfrastructure starts the container with the host, before any skip condition is evaluated, so a missing runtime fails the run at start. Start the container in the suite fixture instead, before registering anything:

var started = PostgresDatabase.TryStart();
if (!started.Started)
{
    // Fall back to a configured connection string, or skip the suite.
}

PostgresDatabase.TryStart(...) and RabbitMqBroker.TryStart(...) report the failure instead of throwing, so the fixture can fall back, replace the connection string, or skip the suite. When the fixture starts the container itself, register it with AddResource so the host still releases it; AddInfrastructure is for containers the host starts. TryStart blocks the calling thread while the container starts and has no timeout. See Skip conditions.

The browser does not launch

Playwright reports that the browser executable does not exist when it was never installed on the machine. Set InstallBrowsers = true to download it before the first launch, or use Channel = "msedge" or "chrome" to drive a browser that is already installed. On a clean Linux image, the operating-system libraries still come from playwright.ps1 install --with-deps chromium. See Web.

Tests pass alone and fail together

Parallel tests share the application and its data. When two tests create the same customer, order number or email address, one of them fails, but only when they happen to run at the same time.

Make every value a test creates unique to that test. Proto.Context.UniqueName("customer") derives a deterministic name from the test id. See Execution context for the rerun rule:

new { name = Proto.Context.UniqueName("customer") }   // "customer-0042317"

For a one-off value that does not need to survive the run, context.TestId interpolated into the value works too:

new { email = $"customer-{context.TestId}@example.test" }

Tests that genuinely cannot run side by side need the runner's own tool: [NonParallelizable] on NUnit, a collection on xUnit. See Concurrency for what ProtoTest keeps isolated.

Where is the trace?

Without ConfigureTracing, the trace goes to TestResults/prototest-{runId}.prototrace. Relative paths, that one and your own, resolve against the directory the tests run in, which for dotnet test is the test project's output folder: bin/Debug/net10.0/TestResults/. Set an absolute path, or one built from an environment variable, to collect it from CI.

bin/Debug/net10.0/TestResults/*.prototrace   (where dotnet test writes)
  -- upload from the repo root misses it -->
PROTOTEST_RESULTS (absolute; trace and sinks agree)   (where CI looks)

If trace.prototest.dev says the trace is from an older ProtoTest, the file was written by a version whose archive the viewer does not open: it reads spans format 2.x and state format 1.x or 2.x. Run the tests again with a current ProtoTest. The archive itself keeps its shape: manifest format 2.0, spans.json plus state.json, whose state documents are format 1.1.

The CI artifact is empty

No files were found with the provided path.

The trace's default relative path starts below the test process working directory, commonly bin/Release/net10.0/TestResults/, while the CI upload step usually searches from the repository root. Set an absolute PROTOTEST_RESULTS directory and use it for the trace and report sinks as shown in Continuous integration.

Also make the upload step run after failures: if: always() on GitHub Actions, succeededOrFailed() on Azure Pipelines or artifacts: when: always on GitLab. If the upload still fails, print the configured absolute directory once from the suite setup. Do not broaden the artifact glob to the entire workspace, where it can collect unrelated files.

Still stuck?

Open the trace: the test's story shows every hook, request and check in order, and the failure leads with the check that decided it. If that does not explain it, open an issue. Only attach a trace after checking it for application data and secrets.