Troubleshooting
Each error entry is headed by the message Trax raises, quoted as it appears in the source, with
the names it fills in shown as X, Y and Z. Search this page for a distinctive phrase from
the message you have; a startup error ends with a link to its entry here. Problems that raise no
error are at the end.
"Could not find train with input type (X)"
The TrainBus has no train registered for the input's type, and throws NoTrainForInputException. The message names the type, the assemblies the mediator scanned, and the two fixes:
Could not find train with input type (MyApp.Orders.OrderInput): no IServiceTrain<OrderInput, TOut> is registered for it. Scanned assemblies: [MyApp.Api]. Add a train that takes this input type, or add the assembly that holds its train to ScanAssemblies(...).Causes:
- The assembly containing your train is not in the scanned list, because it was never passed to
AddMediatororScanAssemblies - Your train doesn't implement
IServiceTrain<TIn, TOut> - Your train class is
abstract
Fix: add the train's assembly to the scan.
using Trax.Effect.Data.Postgres.Extensions;
using Trax.Effect.Extensions;
using Trax.Mediator.Extensions;
services.AddTrax(trax => trax
.AddEffects(effects => effects.UsePostgres(connectionString))
.AddMediator(mediator => mediator
.ScanAssemblies(typeof(Program).Assembly, typeof(YourTrain).Assembly))
);This is a host configuration error, reported to the host. The exception is not a TrainException, so Trax.Api and the scheduler's runner endpoints, which pass a TrainException's message through as a train's own words, do not pass this one through that way; read it in the host's log. A caller that asks ITrainExecutionService for a train name that does not exist gets TrainNotFoundException instead, whose message is always "The requested train was not found." and does not say what is registered.
The scheduler checks the same thing when a train is scheduled (Schedule, ScheduleMany, ScheduleOnceAsync and the rest) and throws InvalidOperationException with the same fix:
No train implements IServiceTrain<OrderInput, TOut>. Add the train's assembly to AddMediator(m => m.ScanAssemblies(typeof(MyTrain).Assembly)).A scheduled run runs the train it names, so the scheduler also refuses a train that was not scanned when another train takes the same input type: Train 'MyApp.Orders.IOrderTrain' is not registered, although another train takes OrderInput., followed by the same fix.
"AddTraxGraphQL() requires AddTrax() to be called first"
AddTraxGraphQL() checks, when it is called, that AddTrax() has already registered Trax in the
same IServiceCollection.
Cause: AddTrax() was not called, or it was called after AddTraxGraphQL().
Fix: Call AddTrax() first:
using Trax.Api.GraphQL.Extensions;
using Trax.Effect.Data.Postgres.Extensions;
using Trax.Effect.Extensions;
using Trax.Mediator.Extensions;
using Trax.Scheduler.Extensions;
builder.Services.AddTrax(trax => trax
.AddEffects(effects => effects.UsePostgres(connectionString))
.AddMediator(typeof(Program).Assembly)
.AddScheduler()
);
builder.Services.AddTraxGraphQL(); // After AddTrax()"UseTraxApiDashboard() requires the GraphQL operations namespace"
Every page of the operations console reads operations, which AddTraxGraphQL() leaves out until
it is exposed.
Fix: Call ExposeOperationQueries(), and ExposeOperationMutations() for the console's
actions, on the GraphQL builder, with the gate it then asks for (GateOperations(...) or
GateOperationsToAuthenticatedUsers()). See
Add the console to a host.
"Call AddEffects(...) before AddMediator(...)."
The step builder pattern enforces configuration ordering at compile time. AddMediator() is only available on TraxBuilderWithEffects (returned by AddEffects()), and AddScheduler() is only available on TraxBuilderWithMediator (returned by AddMediator()).
Cause: Calling methods out of order. Trax.Mediator and Trax.Scheduler report order mistakes as CS0619 with the fix as the text:
| Error text | Cause |
|---|---|
Call AddEffects(...) before AddMediator(...). | AddMediator() called before AddEffects() |
AddMediator(...) is already called. Call it once and configure everything in that call. | AddMediator() called twice |
Call AddStateMachines(...) before AddMediator(...). | AddStateMachines() called after AddMediator() |
Call AddMediator(...) before AddScheduler(...). | AddScheduler() called before AddMediator(), straight after AddEffects() or on the bare builder |
Call UsePostgres(...), UseSqlite(...) or UseInMemory(...) before AddDataContextLogging(...). | AddDataContextLogging() called before a data provider |
Fix: Follow the required order: AddEffects() -> AddStateMachines() if you use it -> AddMediator() -> AddScheduler():
using Trax.Effect.Data.Postgres.Extensions;
using Trax.Effect.Extensions;
using Trax.Mediator.Extensions;
using Trax.Scheduler.Extensions;
services.AddTrax(trax => trax
.AddEffects(effects => effects.UsePostgres(connectionString)) // Step 1
.AddMediator(typeof(Program).Assembly) // Step 2
.AddScheduler() // Step 3
);"AddScheduler() requires a data provider (UsePostgres(), UseSqlite(), or UseInMemory())"
The scheduler's background services keep manifests, Metadata and work queue entries in the
database, so AddScheduler() refuses a host whose AddEffects(...) names no data provider.
Fix: add one, from its own package (Trax.Effect.Data.Postgres, .Sqlite or .InMemory):
using Trax.Effect.Data.Postgres.Extensions;
using Trax.Effect.Extensions;
using Trax.Mediator.Extensions;
using Trax.Scheduler.Extensions;
services.AddTrax(trax => trax
.AddEffects(effects => effects.UsePostgres(connectionString)) // or UseSqlite(...) / UseInMemory()
.AddMediator(typeof(Program).Assembly)
.AddScheduler()
);"AddJunctionProgress() requires a data provider (UsePostgres(), UseSqlite(), or UseInMemory())"
Junction progress writes the current junction to the run's Metadata row and reads cancellation
requests from it, so it needs a data provider in the same AddEffects(...) call. Add one as above.
"AddStateMachines() requires a data provider"
The state-machine snapshot store keeps drafts and effect claims in the database. Configure a data
provider in AddEffects(...) before calling AddStateMachines(...).
"N of M registered trains cannot run:"
The host refused to start. The mediator's startup check builds every registered train and replays
its chain before the host serves traffic, and found trains that would fail every run. Each
indented line below the heading names one train and one problem, in the form
IMyTrain: step 2 (MyJunction) needs 'Customer' in Memory and nothing before it puts one there.
The entries that follow cover each kind of line. A train the check cannot build outside a request
is not refused: it is logged as a warning, "The chain of X was not verified at startup".
"X cannot be built: its constructor needs 'Y', which is not registered"
The host refused to start because a train's own constructor asks for a type that nothing registers
in the container, so the train would fail every run. Register the type before building the host.
The same refusal names a registered dependency whose own constructor needs an unregistered type,
with the path the train reaches it through: ProbeRepository needs 'IClock', which is not registered, and the train's constructor reaches it through 'IProbeRepository'. A train class with
no public constructor is refused as FooTrain has no public constructor. Give it one. A dependency
registered through a factory that can only build inside a request (one reading HttpContext, say)
is not refused: the train is skipped with a warning, "was not verified at startup".
"X: its [Inject] property 'P' needs 'Y', which is not registered"
The host refused to start because one of the train's own [Inject] properties names a type that
nothing registers. The container fills an [Inject] property with GetService and leaves it null
when nothing is registered, so the train builds and then fails on the run that reads it. Register
the type before building the host. If the train is meant to run without it, declare the property
nullable (IClock? Clock): the check then logs a warning instead of refusing. A property the
train's constructor or an initializer sets is never filled by the container and is not checked, so
giving it a default (= SystemClock.Instance) also clears the refusal. A registered type
whose own constructor needs an unregistered one is refused the same way as a constructor argument,
with the path: ... and the train's [Inject] property 'Repository' reaches it through 'IProbeRepository'.
"Chain<X> builds the junction itself, which never fills [Inject] properties"
A warning, not a refusal. A junction reached with Chain<T>() or ShortCircuit<T>() is built
from its constructor, so the [Inject] properties it declares are null whenever it runs. Take the
dependency as a constructor parameter, or register the junction under an interface and reach it
with IChain.
"Junction 'X' (train 'Y') needs 'Z' as a constructor argument"
A junction's constructor asks for something the chain never produced and the container does not hold. Trax builds a junction through its single public constructor, taking each argument from Memory first and the container second, so the message names the junction, the train and the missing type.
Fix: Register the missing service, or chain a junction that outputs it before this one. On a
generic host the startup chain check finds this before the first run and refuses to start, with
step N (X) needs 'Z' as a constructor argument. The run-time message above is what a host that
skips the check (the Lambda runner, a bare ServiceProvider, SkipChainVerification()) sees.
"Junction 'X' (train 'Y') has 2 public constructors"
Trax builds a junction through its single public constructor. A junction with more than one, or none, cannot be built, so the startup chain check refuses the host naming the junction and the count. Give it exactly one public constructor.
"Junction 'X' (train 'Y') needs 'Z' as its input, but nothing earlier in the chain produced one"
The chain could not find a value of the junction's input type in Memory, and the container does
not register one either. The startup check reports the same problem as
step N (X) needs 'Z' in Memory and nothing before it puts one there.
Causes:
- A previous junction didn't return or add the expected type to Memory
- Type mismatch between junction output and next junction's input
Fix: Check the chain flow. Each junction's input type must exist in Memory (seeded automatically from the train input, or from a previous junction's output):
// Memory starts with: { CreateUserRequest, Unit }
Chain<ValidateJunction>() // Takes CreateUserRequest, returns Unit
.Chain<CreateUserJunction>() // Takes CreateUserRequest, returns User
.Chain<SendEmailJunction>(); // Takes User (from previous junction)The startup chain verification catches these before the host serves traffic: it refuses to start and names the junction and the missing type. (The compile-time Analyzer is deprecated and no longer reports CHAIN001.)
"Unable to resolve service for type 'X' while attempting to activate 'Y'"
This message comes from the .NET DI container, not from Trax: something it is building, usually a
train or a service the train depends on, asks for a type nothing registers. The startup check
reports a train's unregistered dependency itself, as "X cannot be built" above, so this raw message
reaches you only for a train the check did not verify: one it skipped with a "was not verified at
startup" warning, or a host where the check does not run (the Lambda runner, a bare
ServiceProvider, SkipChainVerification()).
Fix: register the missing type before building the host:
services.AddScoped<IUserRepository, UserRepository>();"Manifest group 'X' is given two different Y values"
Two schedules that share a group each state the same group setting (MaxActiveJobs, Priority or Enabled) with different values. Every start writes a stated group setting, so the value in force would depend on which manifest was seeded last, and AddScheduler refuses it. The message names both schedules.
Fix: state the setting on one member of the group, or the same value on each. A member that says only .Group("name") leaves the group's settings alone.
"Batch 'X' prunes manifests whose external ID starts with ..."
One batch's prune prefix starts another batch's, so the first would delete the second's manifests at every start. A name-based ScheduleMany(name, ...) prunes only within its own group, so this is raised only when the groups do not keep the two apart: an explicit PrunePrefix, or two name-based batches moved into one group.
Fix: rename one batch so neither name plus - starts the other, or keep the batches in separate groups.
The same message, ending "which includes '...', scheduled on its own", means a single Schedule falls inside a batch's prune: its external ID starts with the batch's prefix and, for a name-based batch, it is in the batch's group (Schedule("sync-extra", ..., o => o.Group("sync")) beside ScheduleMany("sync", ...), or a plain Schedule("sync-extra") beside a batch with PrunePrefix("sync-")). Each start the batch would delete it with its history and its own schedule would create it again.
Fix: give the single schedule an external ID outside the prefix, put it in a different group (name-based batches only), or make it one of the batch's items.
"Invalid cron expression: 'X'. Expected 5 or 6 space-separated fields."
Schedule.FromCron, which every Cron helper goes through, parses the expression when the
schedule is created and throws this FormatException for an expression with the wrong number of
fields, such as a seven-field one. An expression with the right number of fields but a value out of
range, such as Cron.Daily(hour: 25) or Cron.Hourly(minute: 60), is refused by the Cronos parser
with its own CronFormatException, which is also a FormatException. Fix the value at the call the
stack trace names.
"Cron expression 'X' never fires: it has no occurrence in the next 10 years."
The expression parses but names a date that does not exist, such as 0 0 30 2 * (February 30th).
Check the day of the month against the months it names.
"A schedule interval must be at least one second."
Schedule.FromInterval, and so every Every helper, throws this ArgumentOutOfRangeException
for an interval shorter than one second, including Every.Seconds(0). The manifest stores whole
seconds, so a shorter interval would be stored as zero.
"The type or namespace name 'IManifestProperties' could not be found"
The compiler's CS0246. IManifestProperties lives in the Trax.Effect package, not in
Trax.Scheduler, in the namespace Trax.Effect.Models.Manifest.
Fix:
using Trax.Effect.Models.Manifest;Train completes but metadata shows "Failed"
Check FailureException and FailureReason in the metadata record for details. FailureJunction identifies which junction threw, and StackTrace points to the original throw site. Common causes:
- An effect provider failed during
SaveChanges(database connection, serialization error) - A junction threw after the main train logic completed
If you catch the exception outside Trax, you'll see the original exception type and message. Structured junction context is available via exception.Data["TrainExceptionData"].
Junctions execute out of order or skip unexpectedly
A junction reached with ShortCircuit that throws is ignored and the train continues. One that
returns a value sets what Resolve() returns, and the Chain steps after it still run. See
ShortCircuit.
Scheduled jobs don't execute (no errors)
Possible causes:
- The manifest's
IsEnabledisfalse. Check viaITraxScheduleror the database. A disabled manifest's already-queued scheduled entries also wait,Queued, until it is re-enabled; only a trigger or a dead-letter requeue runs it while disabled. A restart does not re-enable a manifest or group that was disabled at runtime unless the code states.Enabled(true)(see What a Restart Rewrites) - A new cron schedule has not reached its first occurrence yet. It first runs at its first occurrence after it was scheduled, not on the next poll, and cron times are UTC:
Cron.Daily(hour: 3)is 03:00 UTC. The manifest'sNextScheduledRunshows when that is ManifestManagerPollingIntervalorJobDispatcherPollingIntervalis set too high and the job hasn't been picked up yet
SDK Reference
AddTrax / AddEffects | AddMediator | UseTraxApiDashboard | AddTraxGraphQL | UseInMemory