DATA
Data
Are teacher, lesson, class, weekly-hour and timetable data correct?
Help Center · Troubleshooting
Find which layer owns the problem before changing anything.
The same symptom can have different causes in Dersiva. An unplaced lesson may be a mathematical capacity problem, while an abrupt process exit may point to the runtime or native solver layer. Diagnosis is faster than random configuration changes.
Four diagnostic layers
Classify the problem before attempting a fix.
RULES
Constraints
Are unavailable days, daily limits, blocks or shared lessons locking the solution space?
RUNTIME
Runtime
Are the application, .NET, native OR-Tools components and Visual C++ runtime healthy?
PUBLISH
Publishing / connectivity
Are API, licensing, Teacher Portal or output snapshots using the correct source?
Quick symptom map
Use the visible symptom to choose the first checkpoint.
Application does not start
Installation / runtime
→Application closes during generation
Runtime / native solver
→Some lessons remain unplaced
Data / capacity / hard constraints
→License verification fails
Network / DNS / API
→Portal does not update
Applied timetable / API / portal
→PDF/output looks stale
Timetable snapshot / output source
→Backup will not restore
File / version / restore scope
→01
Define the symptom together with the workflow stage
Replace “it does not work” with the exact stage: application startup, data entry, solver start, solver execution, timetable completion, publishing, output generation or restore. The same error message can mean different things at different stages.
02
Record version, time and execution mode
When the problem occurs, note the Dersiva version, approximate time, generation mode, whether Safe Diagnostic Mode was enabled and the visible error text. Time information makes log and Windows event correlation much faster.
03
Back up before major troubleshooting changes
Before removing constraints in bulk, resetting data, reinstalling or restoring another backup, create a current `.ddbackup`. Troubleshooting should not turn into a data-loss event.
04
Validate the core data model first
Teacher planned weekly loads, class/section hours, lesson assignments and school time structure must agree. Incorrect weekly hours or missing assignments can produce failures independently of the solver implementation.
05
Diagnose unplaced lessons layer by layer
For an unplaced lesson, inspect teacher availability, daily maximum, class open periods, shared lessons and other hard conditions together. An unplaced lesson is not the same as an application crash; it normally requires feasibility and capacity analysis.
06
Separate hard-constraint conflicts
Unavailable days, exact daily maxima, mandatory blocks, shared-lesson synchronization or protected days can each be valid while their combination makes the model infeasible. Avoid turning preference-like conditions into hard constraints unnecessarily.
07
Do not confuse poor quality with a technical failure
A timetable can be 100% complete but still have poor gaps or daily density. That is a quality-optimization problem. Failure to build a timetable, unplaced lessons and a process crash require different diagnostic paths.
08
If the application exits during generation, inspect the runtime layer
If the process closes without a normal error dialog or Windows logs show a `Google.OrTools.Sat.SolveWrapper.Solve` / native call chain, inspect runtime and native solver dependencies before changing timetable data. This is not the same as a mathematical “no solution” result.
09
Compare with Safe Diagnostic Mode — 1 Worker
If normal multi-worker generation exits but the same data runs in 1 Worker safe mode, that is a useful diagnostic signal. It is not definitive proof of cause, but it points toward worker/native runtime behavior, processor environment and dependency comparison.
10
Verify OR-Tools native and the Visual C++ runtime
The solver uses native OR-Tools components in addition to managed .NET code. Missing, damaged or incompatible runtime components such as Microsoft Visual C++ 2015–2022 Redistributable x64 can affect native calls. Verify current installation prerequisites.
11
Compare environments when the same backup behaves differently
If the same Dersiva version and `.ddbackup` work on one computer but fail at the same stage on another, do not immediately change the data. Compare Windows version, Visual C++ runtime, processor/worker behavior, security software and installation integrity.
12
Read `log.txt` and global error records by timestamp
Search Dersiva diagnostic records for the error time, operation and managed exception information. If the process exits in native code before a managed exception is recorded, `log.txt` may be incomplete and Windows event logs become more important.
13
Inspect the Windows Application event
For abrupt exits, review the Windows Application log for the faulting module and .NET/CoreCLR stack. Seeing `SolveWrapper_Solve` identifies that the failure occurred during the OR-Tools solve call, but it does not by itself identify the root cause.
14
Split license or API failures end to end
Working internet access does not prove that the API is reachable. Check DNS resolution, HTTPS access, school-network filtering/security, the relevant Dersiva domain and the API response separately. Browser access and application/API access are not identical tests.
15
Trace Teacher Portal publishing through four checkpoints
First verify that the correct timetable is selected as applied. Then check the desktop publication snapshot, data sent to the API, server-side source revision and portal presentation in order. A trial timetable must not replace the official portal source.
16
If outputs are stale, verify the snapshot source
If a PDF or other output shows an unexpected timetable, identify which timetable snapshot generated it. Last timetable, trial timetable and applied timetable are different concepts. A technically correct PDF from an old snapshot is still the wrong output for the user.
17
For restore failures, separate file, scope and version
Check `.ddbackup` accessibility, selected restore scope and target Dersiva version. During migration, use the supported restore workflow rather than directly copying the old application folder or machine-specific security keys.
18
Prepare a safe diagnostic package when escalation is needed
Collect Dersiva version, problem time, workflow stage, selected mode, visible error text, the relevant `log.txt` section and Windows event information where necessary. Do not include passwords, license secrets or unnecessary personal data.
First five-minute check
Use this order before making changes.
Classify
Data, constraints, runtime or publishing?
Record state
Version + time + mode + error text.
Create backup
Make a return point before changes.
Run the smallest test
Use 1 Worker, one sample account or one output where appropriate.
Follow evidence
Fix only the layer supported by logs and behavior comparison.
Most expensive troubleshooting mistake
Changing many variables at once before collecting evidence.
Removing constraints, reinstalling the application, restoring backups and changing network settings simultaneously hides the root cause. Change one variable at a time and record the result.
Help Center