Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Docs: on xe there is no SSD expert tier, and --spec 0 is refused for native packs, but the Intel docs and TROUBLESHOOTING say otherwise

Closed Beginner friendly
  • Is something wrong?
#1,796 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 2 days

@nekomario28 is already working on this.

Since Oct 12, 2026.

  • #2153 by @nekomario28 — open

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
72/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
cpp
Domain
ai, documentation

Research direction

Start with the two contradicting passages: docs/INTEL.md:394-395 and docs/INTEL_ARC.md:152-154, then the A750 text at docs/INTEL.md:693-702 that is correct. Check the engine guards at sycl/src/program/generate.cpp:4736-4741 and :2630-2635 to confirm the behaviour before editing. Also update docs/TROUBLESHOOTING.md:124 for native packs. Done when the B70/xe docs state that every expert must sit in VRAM or the RAM mirror, and native packs need --spec 2 or higher.

Written by the indexing model from the issue text.

Description

Environment

  • Ubuntu 26.04.1, kernel 7.0.0-34, 2× Intel Arc Pro B70 (xe)
  • compute-runtime 26.31.39395.14, oneAPI DPC++ 2026.1.1
  • Native build (no Docker), AOT -DSTRATA_SYCL_AOT=bmg-g31
  • Strata fb58e0d (v0.1.41)
  • Config as setup.sh --backend sycl writes it for a B70: --stream-experts, with STRATA_VERIFY_NO_HOST=1 from the wrapper

Summary. There are two engine behaviours a B70 user hits that the docs either leave out or contradict.

a. With STRATA_VERIFY_NO_HOST=1, any expert that is neither in VRAM nor in the mirror makes the engine refuse to start
  • Engine: sycl/src/program/generate.cpp:4736-4741 
    strata generate: REFUSED: %lld experts are neither in VRAM nor mirrored; with STRATA_VERIFY_NO_HOST the device plan
cannot run them and generation would lack a safe host fallback - raise STRATA_MIRROR_MIB or the free RAM, or lower --max-context
    We saw 8290 experts are neither in VRAM nor mirrored ... when we capped VRAM and the mirror to test an SSD tier.
  • docs/INTEL_ARC.md:152-154 says STRATA_VERIFY_NO_HOST=1 "is needed on xe cards when part of the experts is
    not in VRAM", but not that the experts must then all be in VRAM or the pinned mirror, with no SSD fallback.
  • docs/INTEL.md:394-395 contradicts the engine: "with --stream-experts there is no host copy of the experts,
    so any expert left out of VRAM is read from the SSD and computed on the CPU whenever it is routed". With the
    wrapper's default (docs/INTEL.md:72-75) the engine refuses instead. This text looks older than the 4736 guard.
  • The only correct description is in the A750 section (docs/INTEL.md:693-702), which a B70 user has no reason to read.

Expected (docs): a short statement in the B70 / xe part of INTEL.md and in INTEL_ARC.md, something like:
"On xe (STRATA_VERIFY_NO_HOST=1) every expert must be in VRAM or in the pinned RAM mirror
(STRATA_MIRROR_MIB). There is no SSD expert tier; if the two do not cover the model, the engine refuses to start.
Size RAM accordingly, or lower --max-context." Also fix or remove INTEL.md:394-395.

b. --spec 0 (or 1) is refused for native (IQ) packs
  • Engine: sycl/src/program/generate.cpp:2630-2635 (and upstream src/program/generate.cpp:2587): 
    strata generate: %s is a native (IQ) pack: it needs --native SHARD1, --spec T (T >= 2) and --prefill CHUNK
  • docs/TROUBLESHOOTING.md:124 tells users that "--spec 0 avoids the verify window while you wait for a driver
    fix". For a native pack that advice ends in this refusal. Neither INTEL.md nor INTEL_ARC.md says that
    speculative decoding cannot be turned off for native packs, so "spec on vs off" cannot be A/B tested on them.

Expected (docs): state the --spec >= 2 requirement for native packs next to the --spec examples in
INTEL.md (e.g. near :208-220, :293). In TROUBLESHOOTING.md:124, give the workaround that does work for native
packs (--spec 2, the smallest window?), or say that --spec 0 applies only to non-native packs.

Suggested fix: docs only. Optionally, make the 2632 message say why T must be at least 2, and the 4738 message
say "there is no SSD fallback on this path", so the error itself points users to the docs.

Related (not duplicates): open #1440 (2× B70, --layer-split) hits the same REFUSED: ... neither in VRAM nor mirrored line. There the cause is a mirror bug on a split; here it is the documented single-card tier rule. Linking
both helps the docs fix land in the right place. Open PR #1390 edits docs/INTEL.md (Windows), so expect a
conflict there. Nothing found on --spec 0 for native packs.

Dominant language
C++
Stars
11.6k
Forks
1k
No merged PRs in 30d

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Niko1221/Strata

All issues in Niko1221/Strata

Similar issues

More C++ issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.