Repository navigation
Troubleshooting Guide
Identify · Diagnose · Resolve · Verify
A structured troubleshooting reference for installation, tensor operations, gradients, model training, CUDA, serialization, interoperability, and development workflows.
Home · Installation · API Reference · Testing and Quality Assurance
Repository: krishanth7/EveryO
Maintainer: @krishanth7
Support: Community-maintained, best-effort
Important
Before Troubleshooting
Use a supported Python environment, confirm the installed EveryO version, and run everyo doctor.
EveryO is experimental alpha software. The project does not claim to be a production training runtime.
This guide covers common failure patterns. The precise cause of any error must be established using its traceback and a reproducible example.
- Troubleshooting Overview
- Quick Diagnostic Checklist
- Supported Environment
- Diagnostic Commands
- Installation Problems
- Import Errors
- Python Environment Conflicts
- Tensor Creation Errors
- Shape and Broadcasting Errors
- Automatic Differentiation Errors
- Gradient Verification
- Neural Network Errors
- Training Problems
- Loss and Optimizer Problems
- DataLoader Problems
- Serialization Problems
- CUDA Problems
- CUDA Build Problems
- Mixed Precision Problems
- ONNX Problems
- Distributed Training Problems
- Performance Problems
- CLI Problems
- Testing and CI Problems
- Security Considerations
- Issue Reporting and Escalation
- Troubleshooting Decision Tree
- Frequently Asked Questions
- Official References
- Final Checklist
Effective troubleshooting starts by separating an observed symptom from its underlying cause.
An installation error, a tensor shape mismatch, and an incorrect gradient require different diagnostic approaches.
ERROR OCCURS
|
v
Capture Error
|
v
Check Environment
|
v
Reproduce Minimally
|
v
Isolate Component
|
v
Apply Correction
|
v
Run Verification
|
+-----+-----+
| |
v v
Resolved Unresolved
|
v
Report Issue
- Preserve the complete traceback.
- Change one variable at a time.
- Verify package and Python versions.
- Reproduce the failure using the smallest possible example.
- Distinguish unsupported functionality from defective behavior.
- Do not assume that successful installation proves runtime compatibility.
Before investigating a complex problem, check the following.
- Python version is supported.
- The intended virtual environment is active.
- EveryO is installed in that environment.
- Required dependencies are available.
-
everyo doctorcompletes or provides actionable diagnostics. - The failure can be reproduced.
- Input tensor shapes and dtypes are known.
- Optional hardware and dependencies are available when required.
- Relevant tests have been run.
- No sensitive information appears in shared logs.
EveryO's documented compatibility baseline includes Python 3.9 through 3.12.
| Component | Requirement |
|---|---|
| Python | 3.9–3.12 documented |
| NumPy | 1.22 or later |
| Matplotlib | 3.5 or later |
| GPU | Not required |
| Internet | Not required for core runtime after installation |
| API keys | Not required |
| Feature | Dependency |
|---|---|
| TensorFlow comparisons | tensorflow>=2.12 |
| YAML | PyYAML>=6.0 |
| ONNX | onnx>=1.15 |
| ONNX Runtime | onnxruntime>=1.17 |
| CUDA build |
pybind11>=2.11 and native toolchain |
| Development | pytest, pytest-cov, Ruff |
The package's declared minimum dependency versions do not guarantee that every combination is compatible with every Python version or operating system.
python --versionpython -c "import sys; print(sys.executable)"python -c "import everyo; print(everyo.__file__)"python -m pip show everyoeveryo doctorpython -m pip checkFrom the repository root:
python -m pytest -qruff check .
ruff format --check .Possible causes:
- Unsupported Python version.
- Incompatible dependency versions.
- Incorrect working directory.
- Network restrictions during dependency installation.
- Build tool problems.
Create a fresh virtual environment.
python -m venv .venvActivate it.
Linux/macOS:
source .venv/bin/activateWindows PowerShell:
.\.venv\Scripts\Activate.ps1Install EveryO from the repository root:
python -m pip install -e .Install:
python -m pip install -e ".[dev]"Inspect the full pip output.
Do not automatically upgrade every package without identifying the incompatible requirement.
ModuleNotFoundError: No module named 'everyo'
- EveryO is not installed.
- The wrong Python interpreter is active.
- The virtual environment is inactive.
python -m pip install -e .Then:
python -c "import everyo; print(everyo.__file__)"Example:
ModuleNotFoundError: No module named 'onnx'
Install the relevant optional dependency group:
python -m pip install -e ".[onnx]"For TensorFlow:
python -m pip install -e ".[tensorflow]"Avoid naming your own scripts:
everyo.py
numpy.py
tensorflow.py
Such filenames can shadow installed packages.
A common failure occurs when installation and execution use different Python interpreters.
Compare:
python -c "import sys; print(sys.executable)"With:
python -m pip --versionUse:
python -m piprather than relying on an unrelated pip executable.
If the environment is heavily modified, reproduce the problem in a new virtual environment before changing the existing one.
import everyo as eo
x = eo.tensor(
[1.0, 2.0, 3.0],
requires_grad=True,
)
print(x)- Unsupported dtype.
- Ragged input arrays.
- Invalid device request.
- Unexpected tensor shape.
import everyo as eo
x = eo.tensor([[1.0, 2.0], [3.0, 4.0]])
print("Shape:", x.shape)
print("Dtype:", x.dtype)
print("Device:", x.device)Inspect the input data before performing operations.
Use consistent numerical dtypes and explicit shapes when debugging.
For matrix multiplication:
[ A_{m\times n}B_{n\times p} ]
The inner dimensions must match.
Example:
A shape: (4, 8)
B shape: (8, 3)
Result: (4, 3)
Invalid example:
A shape: (4, 8)
B shape: (7, 3)
Inner dimensions do not match.
Broadcasting requires compatible dimensions.
Examples:
| Shape A | Shape B | Expected Compatibility |
|---|---|---|
(4, 3) |
(3,) |
Compatible |
(4, 3) |
(1, 3) |
Compatible |
(4, 3) |
(4, 1) |
Compatible |
(4, 3) |
(5, 3) |
Incompatible |
Print tensor shapes before the failing operation.
Check whether the intended operation is:
- Element-wise multiplication.
- Matrix multiplication.
- Reduction.
- Broadcasting.
These operations have different shape rules.
Check whether the tensor requires gradients.
import everyo as eo
x = eo.tensor([2.0], requires_grad=True)
y = x * x
y.backward()
print(x.grad)Expected numerical result:
[4.]
- Gradient tracking disabled.
- Tensor detached from the computational graph.
- An operation that does not support differentiation.
- Incorrect backward usage.
- Unexpected gradient accumulation.
- Confirm
requires_grad=True. - Reduce the computation to a small example.
- Verify the expected derivative manually.
- Inspect the backward result.
- Compare against finite differences.
When performing multiple backward passes, verify whether existing gradients must be cleared before the next optimization step.
An incorrect gradient can make training fail even when the forward calculation appears correct.
\frac{f(x+h)-f(x-h)}{2h} ]
Absolute error:
[ E_{\text{abs}} = |g_{\text{analytic}}-g_{\text{numeric}}| ]
Relative error:
[ E_{\text{rel}} = \frac{|g_{\text{analytic}}-g_{\text{numeric}}|} {\max(\epsilon,|g_{\text{analytic}}|,|g_{\text{numeric}}|)} ]
- Use float64 where supported.
- Choose an appropriate finite-difference step.
- Avoid non-differentiable points.
- Test multiple input shapes.
- Use both absolute and relative tolerances.
A failed finite-difference comparison may indicate:
- Incorrect backward logic.
- A numerical precision problem.
- A poorly chosen finite-difference step.
- Evaluation at a non-differentiable point.
Investigate before changing tolerance values.
A linear layer's input feature count must match its configured in_features.
Example:
import everyo as eo
layer = eo.Linear(4, 8)
x = eo.tensor([[1.0, 2.0, 3.0, 4.0]])
y = layer(x)
print(y.shape)Expected shape:
(1, 8)
If a layer expects four features, passing three features will not satisfy the layer's shape contract.
Confirm trainable parameters are registered correctly when implementing custom modules.
Use the appropriate training or evaluation mode for layers whose behavior changes between training and inference.
Possible causes:
- Learning rate too high.
- Learning rate too low.
- Incorrect labels.
- Incompatible output and loss shapes.
- Missing gradient updates.
- Incorrect data preprocessing.
- Numerical instability.
- Train on a very small dataset.
- Verify model outputs.
- Verify target values.
- Inspect loss.
- Check gradients.
- Confirm optimizer updates.
- Increase dataset size gradually.
import everyo as eo
model = eo.Sequential(
eo.Linear(4, 16),
eo.ReLU(),
eo.Linear(16, 2),
)
optimizer = eo.Adam(
model.parameters(),
lr=0.001,
)
loss_fn = eo.CrossEntropyLoss()Connect the model, optimizer, and loss to a properly configured training dataset.
Investigate:
- Non-finite input values.
- Excessively large updates.
- Invalid loss inputs.
- Division by zero.
- Overflow.
- Unstable operations.
Reducing the learning rate may help, but the underlying cause should still be identified.
Choose the loss according to the task.
| Task | Common Loss |
|---|---|
| Regression | Mean squared error |
| Classification | Cross-entropy |
| Binary classification | Binary cross-entropy |
Verify the expected target format for the selected loss.
For classification, check whether the API expects class indices or another target representation.
Confirm:
- The optimizer receives model parameters.
- Gradients are available.
- The learning rate is appropriate.
- Parameters actually change after an update.
Inspect optimizer state, gradient magnitudes, and the loss calculation.
- Unexpected batch shape.
- Inconsistent labels.
- Incorrect sample ordering.
- Missing samples.
- Invalid dataset indexing.
Print:
- Dataset length.
- Batch size.
- First batch shape.
- Label shape.
- Feature dtype.
Use controlled random seeds where supported.
Verify that input samples and target labels remain aligned after preprocessing or shuffling.
EveryO uses .evo model archives.
import everyo as eo
model = eo.Sequential(
eo.Linear(4, 8),
eo.ReLU(),
eo.Linear(8, 2),
)
eo.save(model, "model.evo")restored = eo.load("model.evo")- Missing file.
- Corrupted archive.
- Incompatible architecture.
- Parameter shape mismatch.
- Unsupported module type.
- Invalid archive metadata.
- Confirm the file exists.
- Verify the archive was created successfully.
- Check model compatibility.
- Confirm custom modules are properly registered.
- Reproduce using a minimal model.
EveryO's .evo format is designed to avoid Python pickle execution.
Nevertheless, untrusted files should be handled with appropriate resource and integrity controls.
CUDA is optional.
EveryO should remain usable on CPU-only systems.
import everyo as eo
print(eo.cuda.is_available())
print(eo.cuda.device_count())
print(eo.cuda.unavailable_reason())import everyo as eo
print(eo.cuda.runtime_info())- No compatible NVIDIA GPU.
- Missing native extension.
- Incompatible CUDA runtime.
- Driver problems.
- CUDA explicitly disabled.
import everyo as eo
device = eo.device("cuda")
print(device)When CUDA is unavailable, the documented non-strict device request falls back to CPU with a warning.
import everyo as eo
device = eo.device("cuda", strict=True)If CUDA is unavailable, strict mode raises an error instead of silently selecting CPU.
For diagnostic purposes, the documented environment variable is:
EVERYO_DISABLE_CUDA=1Set it in the environment before starting Python.
The documented CUDA build requires:
- NVIDIA CUDA Toolkit.
-
nvcc. - CMake 3.18 or later.
- pybind11.
- Compatible compiler and platform.
A compatible GPU is required for execution, although compilation may be possible without one.
python -m pip install -e ".[cuda]"./scripts/build_cuda.shcmake -S cuda -B build/cuda -DCMAKE_BUILD_TYPE=Release
cmake --build build/cuda --parallel- CUDA Toolkit installed.
-
nvccaccessible. - CMake available.
- Compatible compiler configured.
- pybind11 installed.
- Correct Python environment active.
- Build logs reviewed.
A GPU is not automatically faster for small operations.
Host-device transfers may outweigh kernel execution time.
EveryO includes mixed-precision utilities.
- Gradient underflow.
- Non-finite values.
- Unexpected numerical differences.
- Slower execution on CPU.
Float16 represents a smaller numerical range than float32.
Very small gradient values may round to zero.
Loss scaling increases gradient magnitudes during backward computation to reduce underflow.
- Compare with float32 execution.
- Inspect gradient values.
- Verify scaling behavior.
- Check for NaN or infinity.
- Use appropriate precision for the workload.
Mixed precision is not guaranteed to improve CPU performance.
The README notes that NumPy float16 arithmetic can be slower because computation may involve upcasting.
EveryO supports ONNX export for documented model types.
python -m pip install -e ".[onnx]"import everyo as eo
model = eo.Sequential(
eo.Linear(4, 8),
eo.ReLU(),
eo.Linear(8, 2),
)
model.eval()
eo.export_onnx(
model,
"model.onnx",
input_shape=(1, 4),
)- Unsupported operation.
- Missing optional dependencies.
- Unexpected input shape.
- Incorrect tensor layout.
- Static tracing limitations.
- Numerical disagreement.
EveryO convolution operations use NHWC layout.
ONNX convolution operators use NCHW layout.
Export logic must account for this difference.
A traced graph records the executed path.
For recurrent models, sequence length and other shape assumptions may be fixed by the example input.
Run the exported model through ONNX Runtime and compare outputs against EveryO.
A structurally valid ONNX model is not sufficient proof of numerical equivalence.
Distributed execution introduces communication and synchronization concerns.
- Worker hangs.
- Connection failures.
- Inconsistent gradients.
- Process crashes.
- Incorrect worker configuration.
Verify:
- Worker count.
- Process rank.
- Network connectivity.
- Port configuration.
- Identical model initialization.
- Consistent tensor shapes.
- Verify single-process training.
- Verify multiple processes on one machine.
- Verify communication configuration.
- Test across machines only after local validation.
- Compare numerical results.
EveryO's documented TCP process-group implementation assumes a trusted network.
Do not expose it to untrusted networks without appropriate protection.
Potential causes:
- Large tensor dimensions.
- Python execution overhead.
- Frequent host-device transfers.
- Inefficient batching.
- Excessive logging.
- Unsupported acceleration paths.
Measure:
- Batch size.
- Operation latency.
- Epoch duration.
- Memory usage.
- Hardware configuration.
EveryO includes profiling utilities.
Consult the API documentation for the supported profiling interface and available output formats.
Example repository benchmark:
python benchmarks/benchmark_matmul.py --sizes 128 512 1024 2048Use equivalent:
- Input shapes.
- Dtypes.
- Hardware.
- Warm-up procedures.
- Measurement methods.
EveryO provides the everyo command-line interface.
The README documents:
everyo info
everyo doctor
everyo benchmark
everyo test
everyo demo
Check whether the virtual environment is active.
Then reinstall:
python -m pip install -e .Verify the executable location.
Linux/macOS:
command -v everyoWindows PowerShell:
Get-Command everyoStart with:
everyo doctorpython -m pytest -qpython -m pytest --cov=everyoruff check .ruff format --check .Some tests require optional dependencies or hardware.
A skipped CUDA test on a machine without CUDA is not automatically a defect.
Check:
- Python version.
- Operating system.
- Dependency versions.
- Environment variables.
- Available hardware.
The repository pins Ruff to a specific version for development to reduce formatting differences between local machines and CI.
Remove:
- Passwords.
- API keys.
- Tokens.
- Private keys.
- Sensitive filesystem paths.
Treat untrusted archives as potentially malformed or resource-intensive, even when the format avoids pickle execution.
Native code may introduce memory-safety risks and should be tested carefully.
Do not disclose security vulnerabilities in public issues.
Use:
GitHub Private Vulnerability Reporting
If the problem remains unresolved, create a reproducible report.
| Problem | Recommended Channel |
|---|---|
| Reproducible bug | GitHub Issues |
| Usage question | GitHub Discussions |
| Feature request | Feature request issue |
| Security vulnerability | Private vulnerability report |
# Bug Report
## Summary
Describe the problem.
## Environment
- EveryO version:
- Python version:
- Operating system:
- CPU/GPU:
- Installation method:
- Optional dependencies:
## Reproduction Steps
1.
2.
3.
## Minimal Reproducible Example
```python
# Insert minimal example here.Describe the expected result.
Describe the observed result.
Paste sanitized traceback here.
List commands and checks already attempted.
Provide relevant information.
## 26.3 Support Expectations
Community support is provided on a best-effort basis.
There is no guaranteed response time.
---
# 27. Troubleshooting Decision Tree
```text
START
|
v
Does import succeed?
/ \
No Yes
| |
v v
Check Python Run doctor
environment |
| v
| Is CUDA needed?
| / \
| No Yes
| | |
| v v
| CPU tests CUDA checks
| | |
+---------+---------+
|
v
Reproduce Error
|
v
Identify Component
|
+------------+------------+
| | |
v v v
Tensor Training Export
| | |
v v v
Shapes Gradients ONNX checks
| | |
+------------+------------+
|
v
Verify Fix
|
+------+------+
| |
v v
Resolved Report Issue
Why does EveryO report that CUDA is unavailable?
A compatible GPU, working runtime, and built native extension are required.
Run everyo doctor and inspect eo.cuda.unavailable_reason().
Can EveryO run without a GPU?
Yes. The core framework runs on CPU.
Why is my gradient missing?
Check gradient tracking, graph connectivity, and backward usage.
Start with a minimal scalar example.
Why does ONNX output differ slightly?
Small differences can arise from floating-point rounding and execution order.
Large differences require further investigation.
Why does mixed precision run slower on CPU?
NumPy may upcast float16 values for computation, introducing overhead.
Does passing all CPU tests prove CUDA correctness?
No. CUDA runtime correctness requires appropriate GPU testing.
Where can I report a bug?
Use the project's GitHub bug-report template.
Does EveryO provide guaranteed technical support?
No. Support is community-maintained and best-effort.
| Resource | Link |
|---|---|
| EveryO Repository | GitHub |
| README | README.md |
| Installation Guide | Getting Started |
| CUDA Documentation | docs/cuda.md |
| Architecture | docs/architecture.md |
| API Reference | docs/api-reference.md |
| Support Policy | SUPPORT.md |
| Security Policy | SECURITY.md |
| Contributing | CONTRIBUTING.md |
| Bug Reports | GitHub Issues |
| Discussions | GitHub Discussions |
| CI Workflows | GitHub Actions |
Before requesting support:
- Verify the Python version.
- Activate the correct environment.
- Confirm EveryO installation.
- Run
everyo doctor. - Capture the complete error.
- Reduce the problem to a minimal example.
- Check shapes, dtypes, and devices.
- Verify optional dependencies.
- Run relevant tests.
- Remove secrets from logs.
- Search existing issues.
- Submit a clear report if unresolved.
Reliable debugging begins with reproducible evidence.
Next Recommended Page: Best Practices →
Home · Installation · API Reference
EveryO — Open Machine Learning. Built for Developers.
Project Maintainer: @krishanth7
Open Source · MIT Licensed · Community Driven
© 2026 EveryO Contributors