🐛 A failing filter aborts the build in `needs_constraints`, needflow `:highlight:`, needgantt `:milestone_filter:` and needsequence `:filter:`, but only warns everywhere else
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 3/5
- Estimated time
- Half a day
- Newbie friendliness
- 42/100
Research direction
Start with filter_single_need in sphinx_needs/filter_common.py where NeedsInvalidFilter is raised, and with process_filters (around lines 675-685) as the model for the warn-and-skip behaviour. The four aborting callers are need_constraints.py line 45, directives/needflow/_model.py around 504-506, directives/needgantt.py around 248-254 and 330-336, and directives/needsequence.py around 386-392. Done means each surface warns once with its name and the filter and treats the need as unmatched, with a test per surface. Confirm the uniform rule with maintainers before changing behaviour.
Written by the indexing model from the issue text.
Description
A filter string that fails (a NameError on a misspelled field, a non-boolean result) is reported as one needs.filter warning and the need is excluded in directive :filter: options, needextend, needs_warnings strings, needs_builder_filter, needpie, needbar and :need_count: (filter_common.py:675-685, :706-716). The same failure aborts the build on four surfaces, because filter_single_need raises NeedsInvalidFilter (filter_common.py:836, :865) and these callers do not catch it:
needs_constraintschecks (need_constraints.py:45) — "Sphinx error!"- needflow
:highlight:(directives/needflow/_model.py:504-506) - needgantt
:milestone_filter:(directives/needgantt.py:248-254,:330-336) - needsequence
:filter:(directives/needsequence.py:386-392)
Measured at master 3210ac5c (2026-10-14) with one scenario build per surface. A fifth outcome exists too: derive where/test predicates and links_from_* swallow the error silently (functions/common.py:1146-1149, :713-715).
Proposal: one rule for every surface — warn once naming the surface and the filter, treat the need as not matched — with the four aborting callers catching NeedsInvalidFilter the way process_filters does, and the silent ones warning once.
- Dominant language
- Python
- Stars
- 309
- Forks
- 103
- Avg merge
- 4h 26m
- Merged PRs (30d)
- 163
Getting set up
This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from useblocks/sphinx-needs
-
🐛 A `:hide:` need that is the first child of its container gets empty `sections` and no `signature`Openbug pkg: sphinx-needs
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
useblocks/sphinx-needs#2398 ·
Maintainers usually reply within 1 day
-
bug pkg: sphinx-needs
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
useblocks/sphinx-needs#2338 ·
Maintainers usually reply within 1 day
-
bug pkg: sphinx-needs
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
useblocks/sphinx-needs#2335 ·
Maintainers usually reply within 1 day
-
bug pkg: sphinx-needs
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
useblocks/sphinx-needs#2332 ·
Maintainers usually reply within 1 day
-
📚 the "own service" example in docs/services/index.rst cannot be registeredPossibly taken @chrisjsewell claimed this 11 days ago. Opendocumentation pkg: sphinx-needs
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
useblocks/sphinx-needs#2327 ·
Maintainers usually reply within 1 day
All issues in useblocks/sphinx-needs
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 86/100
-
Validate finite output clamping limits in StepPredictor.prepare_clamping_params to prevent silent NaN/Inf propagationPossibly taken @muskan-creates352 claimed this today. Open
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
mllam/neural-lam#848 ·
Maintainers usually reply within 2 days
-
infra
Difficulty 1/5 Under an hour Newbie friendliness 88/100
fab-geocommuns/RNB-coeur#1166 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
deepspeedai/DeepSpeed#8951 ·
Maintainers usually reply within 2 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
aws/context-ontology-accelerator#343 ·
Maintainers usually reply within 1 day