Repository navigation
Troubleshooting
Symptom → cause → fix.
Cause: at least one provider failed or timed out for this call, so coverage is incomplete.
Diagnose: read errors in the response. It names the failing provider and a code.
| Code | Meaning | Fix |
|---|---|---|
UPSTREAM_TIMEOUT |
Provider too slow | Retry; raise FINVIZ_TIMEOUT if persistent |
UPSTREAM_RATE_LIMIT |
Too many requests | Raise TAPEBASIS_<PROVIDER>_MIN_INTERVAL; check rate_limits
|
UPSTREAM_BLOCKED |
WAF rejected the request | Usually transient; check tapebasis_health
|
NO_DATA |
Provider answered, had nothing for this symbol | Check resolutions, then the ticker spelling |
PARSE_ERROR |
Markup/JSON shape changed | See health drift |
NOT_CONFIGURED |
Feature needs a token | Add MARKETAUX_API_TOKEN, or ignore: the data is still served |
A single-source response is not a failure. The data is served and labelled; the notice says it is
not corroborated. BLOOMBERG here means only Bloomberg answered (the bloomberg_* tools ask that one
provider), not that Bloomberg is excluded from ALL: in stock_quote / stock_prices it is a full
leg, and its failures appear as ordinary errors entries. A TIMEOUT from that leg is the 15-minute
delay plus 10 s pacing hitting TAPEBASIS_BLOOMBERG_QUOTE_DEADLINE; the other readings are still
valid; the Bloomberg sections below cover the rest. SA behaves the same way: it is a leg, so its
failure is an ordinary error, while an instrument it does not carry is NOT_ATTEMPTED, not a failure.
Also check providers_answered. ALL means every provider that was asked answered, which can be
only some of them. If a provider is missing from that list and there is no matching errors entry,
look for NOT_ATTEMPTED: the provider does not carry the instrument at all, and resolutions says
why.
Cause: no provider answered.
- Check
errors: usually several entries. - Run
tapebasis_health(refresh=True). - Most common root cause is a lost network path or DNS, not the code.
- For an unknown symbol:
NO_DATAfrom every provider is correct behaviour, not an outage.
Never present a value when data_provider is NONE.
Cause: an upstream changed shape: a renamed JSON field, a moved route, a missing HTML marker. The endpoint still answers 200, which is exactly why this is detected separately.
- Read the probe's
message: it names the field or marker that vanished. - Fetch the endpoint yourself and compare against what the parser expects.
- If upstream genuinely changed: update the parser or shaper, then reset the baseline.
- If the change looks temporary/interstitial: wait one interval, re-check with
refresh=True.
Do not reset the baseline before fixing the parser. That converts a detectable break into a silent wrong answer.
rm ~/.tapebasis/health_state.json # only after fixing the parserCause: normally the print times differ, or a field is derived differently.
- Read
freshness.decisionfirst.newestmeans one provider printed later and its value is the one shown; that is not a conflict. - Read
comparisons[].diff_pct: how far apart, in percent. - Compare against
tolerance_pctfor that field. - Within tolerance →
match: true, no warning. Normal. - Beyond tolerance →
match: false, named innoticeandwarnings. -
match: nullwithnot_comparable: true→ the readings were not judged at all. The reason inpairs[].not_comparablesays which: different session dates, a print past the age ceiling, no print time to prove the observation, a declared feed delay (Bloomberg's 15 minutes), or a field with no shared definition (FX day change).
Check sources before assuming a bug. Each label names the upstream that leg actually called:
TradingView's scanner, finviz.com, query1.finance.yahoo.com, stockanalysis.com and bloomberg.com. A
closed market should agree to the cent; an intraday read legitimately will not.
If a mismatch is systematic on one field, the tolerance may be wrong. See Development § Choosing a tolerance.
Expected, and not a defect. Those fields are measured against the previous close of the session
the print belongs to. Finviz mid-session and Yahoo at the prior close answer two different questions,
so the pair is excluded from the agreement decision with the reason recorded in
pairs[].not_comparable.
The price is compared when the prints are close enough to be the same observation; past that window
it is reported as not_comparable too, with the gap in minutes. A price points at an instant, so two
prints 20 minutes apart are two observations and their difference is the market moving. If you need a
like-for-like day change, compare providers whose freshness timestamps share a session date and are
within 15 minutes of each other.
On FX this is permanent, not a timing accident: spot FX has no single official previous close, so
change_percent is never compared there. The reading from every provider is still reported.
Expected. Bloomberg's equity pages are delayed (exchangeDelay is 15 Minutes), so its print is
older by design. stock_quote already asks Bloomberg and compares it: when its print is a delay length
away from the others, the pair is reported as not_comparable with that reason instead of being
counted as agreement or as a conflict. The single price comes from the newest print, and Bloomberg is
last in the tie-break order, so it never wins one.
Read exchange_delay and print_time in the bloomberg_quote payload before quoting it. If
print_time is null, the intraday series did not end at the quoted price and the response says so in
print_time_missing_reason; that is deliberate, because a timestamp describing a different number is
not a print time.
Cause: bloomberg.com answered 403.
| Symptom | Cause | Fix |
|---|---|---|
UPSTREAM_BLOCKED |
The anti-bot wall, usually after a burst | Wait; the provider pauses itself (rate_limits.BLOOMBERG.cooling_down_s) |
NOT_CONFIGURED |
curl_cffi is not installed |
pip install curl_cffi; the site rejects plain HTTP clients on the TLS fingerprint |
SCHEMA_DRIFT |
The page no longer carries __NEXT_DATA__
|
Treat like any other upstream drift |
NO_DATA |
Bloomberg has no quote for that id | Check the id spelling (AAPL:US, SPX:IND, EURUSD:CUR) |
Bloomberg is deliberately not probed by the health monitor: an httpx probe gets a 403 robot page
from a healthy provider, so it would report a false outage. The tool response itself is the
availability signal, and rate_limits.BLOOMBERG shows whether it is cooling down.
Expected. stock_quote mixes sources: price and core metrics are compared across providers, but
the fundamentals snapshot, company profile, peers and after-hours print exist only on Finviz.
fields exists precisely for this. data_provider: ALL means every provider that was asked answered
for this call, not that every field was covered by every provider. Per-field truth is in fields:
source names the one provider whose value is in data, compared the providers that supplied a
reading for that field, agreement the cross-check result.
Expected, and deliberate. data.price holds one value: the reading chosen as the freshest
print. Four providers supplied a price, they were compared, one won. A field descriptor that said
"ALL" there would read as if the number were a joint product of the four providers when it is one
provider's print. compared names the four; comparisons[].values holds every reading if you need
the others.
Expected when MARKETAUX_API_TOKEN is unset or rejected. The headlines are Finviz's; only the
scoring is local, so the label is FINVIZ.
If you expected the licensed path:
- Check
data.licensed_path_unavailable: it carries the reason. - Most common: no token, expired token, or the daily budget is spent.
-
MARKETAUX_DAILY_BUDGETdefaults to 90 under a 100/day plan.
To use the licensed path, set MARKETAUX_API_TOKEN. To accept local scoring, do nothing.
Cause: there was nothing to score: Marketaux unavailable and Finviz headlines unavailable.
Read note for both reasons. This is deliberate: null means "we could not look", 0.0 would mean
"the news is balanced". They are never conflated, because a data gap must not read as a finding.
Expected sometimes. Scoring is a lexicon over headline text, not comprehension. It cannot parse negation or long-range context, so some headlines will land wrong.
Practical notes:
- It is deterministic and cheap, not accurate in an absolute sense: a triage signal.
-
top_postsshows the highest-conviction headlines, so you can audit what drove the average. -
posts_analyzedtells you the sample size; a score over 3 headlines is weak evidence. - It is not a trading signal, and the payload says so.
If a specific domain word is scored wrong, adding it to the overlay in sentiment.py with an
explicit valence is the fix. Use a float: VADER adds valences arithmetically and a string raises
TypeError.
Expected without MARKETAUX_API_TOKEN: that leg is Marketaux-only. The sentiment leg still works
(local scoring), and data.news says why it is empty. The price cross-check is unaffected.
Cause: one provider hit its HTTP timeout and the others' data still went out. The fan-out waits for every leg, so latency is the slowest one.
Tuning: lower FINVIZ_TIMEOUT (default 25 s) or TAPEBASIS_SA_TIMEOUT (default 20 s) to fail faster,
at the cost of losing slow-but-valid answers. Bloomberg's leg is already bounded by
TAPEBASIS_BLOOMBERG_QUOTE_DEADLINE (12 s), so it becomes a stated TIMEOUT instead of holding the
whole response.
Cause: usually a rate-limit cooldown, not an outage.
- Call
tapebasis_health()and readrate_limits. A positivecooling_down_smeans that provider is in its post-429pause right now, and a risingblock_streakmeans it has been blocked repeatedly. - Let it decay (5 s doubling to 120 s, with jitter). A fan-out over many tickers can trip it.
- If it recurs, raise
TAPEBASIS_YAHOO_MIN_INTERVALfirst: Yahoo is the most sensitive provider. - TradingView's websocket reports a block as
invalid symbol/resolve error. Those are treated as rate limiting, so a burst does not permanently poison the symbol-resolution cache.
Cause: the host's name resolver, not the server. On a machine whose /etc/nsswitch.conf tries
mDNS before DNS (hosts: files mdns4_minimal [NOTFOUND=return] dns), the very first getaddrinfo of
a process costs about 5 s, and every later one about 20 ms. getent hosts is fast because it is a
separate process, so the delay only shows up in-process.
The server resolves every httpx upstream in the background at startup (warm_origins() in the
lifespan, and from /health on transports that ignore the lifespan), so the cost is normally paid
before the first request. If the first call is still slow, the warm-up was cut short: the transport
may not have run either hook, or the resolver is slower than the warm-up allowed.
Fix, when it matters: keep mdns4_minimal out of the hosts: line on a server that does not
need mDNS, or give the container a resolver that answers directly. This is an environment setting;
the server does not change /etc/nsswitch.conf.
Cause: the Bloomberg leg has both a per-page deadline (TAPEBASIS_BLOOMBERG_QUOTE_DEADLINE) and
a total batch budget (TAPEBASIS_BLOOMBERG_BATCH_BUDGET, default 12 s). Its page path is paced at
10 s per request by design, so four tickers used to hold a batch open for 30.5 s. Once the budget is
spent the remaining tickers are named instead of waited out.
That is not a coverage gap: the same ticker answers on the next call, and the page cache (60 s) makes a follow-up cheap. Raise the budget if you would rather wait; do not lower the pacing, which is what keeps the bot wall from closing.
/health reads the cached verdict and makes no upstream call, by design, so a Finviz outage does
not mark the container unhealthy. A stale cache can therefore look green while upstreams are broken.
tapebasis_health(refresh=True)docker compose ps
docker compose logs --tail=100 tapebasis-
start_periodis 15 s; a slow first probe can trip an early check. Wait, then re-check. - Confirm
HOST=0.0.0.0inside the container: loopback makes the port mapping useless. - Confirm the health path is
/health, not/mcp.
Cause: the server is PID 1 and Python does not reap children. Docker starts the HEALTHCHECK
and every docker exec inside the container's PID namespace with a parent outside it, so those
processes are reparented to PID 1 and stay as zombies when nothing calls wait().
Diagnose:
docker top tapebasis -o pid,stat,cmd | head
docker exec tapebasis ps -eo pid,stat,comm | awk '$2 ~ /Z/'Fix: run under an init. The image already does (its entrypoint is tini --), and
docker-compose.yml sets init: true. If you built your own image without tini, add
--init to docker run, or init: true to the compose service.
Zombies are not why the container restarts, but a PID 1 that ignores SIGTERM turns every stop
into the 10 s kill timeout and then a hard SIGKILL; tini forwards the signal so shutdown stays
graceful.
The package is not installed in the interpreter the MCP client uses.
pip install -e .
# or point the client at the venv's absolute path:
# "command": "/absolute/path/.venv/bin/tapebasis"MCP clients do not inherit your shell PATH; absolute paths avoid the whole class of problem.
Read resolutions first. It shows exactly which ticker each provider was asked for and how it was
derived (explicit, alias, search, none).
| Case | Handling |
|---|---|
BRK.B ↔ BRK-B
|
Normalised automatically |
^GSPC ↔ SPX ↔ SP:SPX
|
Aliased to SPX
|
RUT vs IWM
|
Index vs its ETF: different instruments, never aliased |
XAUUSD (spot gold) |
TradingView OANDA:XAUUSD and Bloomberg XAUUSD:CUR. Yahoo has no spot pair (XAUUSD=X is a 404), and Finviz and StockAnalysis do not carry it |
WTI / BRENT / GOLD / SILVER
|
Registry aliases: WTI -> FX:USOIL on TradingView (never NYSE:WTI, an equity), GOLD -> XAUUSD, SILVER -> XAGUSD (TVC:SILVER on TradingView) |
CL1! / GC=F (front futures) |
Same instrument, both spellings: TradingView NYMEX:CL1!, Yahoo CL=F, Bloomberg CL1:COM. Spot (USOIL) and futures (CL1!) are separate rows and never compared with each other |
WTI=F / WTIF
|
Yahoo-style futures spelling meaning the front-month future: aliased to CL1! (TradingView NYMEX:CL1!, Yahoo CL=F, Bloomberg CL1:COM). Left to search, TradingView resolves it to XETR:WTIF, the WisdomTree Japan ETF, a different instrument at a tenth of the price |
NDX / ^NDX
|
Registry row: TradingView NASDAQ:NDX, Yahoo ^NDX, Bloomberg NDX:IND. Finviz and StockAnalysis have no index quote for it (stated boundaries). Not part of the fixed market_indices snapshot list; ask for it with a single-instrument tool |
BTCUSD |
TradingView BITSTAMP:BTCUSD, Yahoo BTC-USD, Bloomberg XBTUSD:CUR; Finviz and StockAnalysis have no crypto |
EURUSD |
TradingView FX:EURUSD, Yahoo EURUSD=X, Bloomberg EURUSD:CUR; Finviz and StockAnalysis have no FX |
SPX / DJI
|
Finviz has no per-ticker index page (/stock?t=SPX is a 404, and COMP there is Compass Inc), and StockAnalysis's quote API has no index route. Use market_indices
|
Non-US (.IS, .CA) |
TradingView only, unless Yahoo or Finviz happens to list it; StockAnalysis's quote API is US-only |
BRK-B |
StockAnalysis spells it brk.b; the dash is converted mechanically |
A resolution of none is not an outage: it means the provider genuinely has no such instrument, and
its note says so. That is why a NONE resolution never appears in errors.
If Finviz silently resolves a delisted/renamed ticker, the response carries ticker_warning with
both the requested and resolved symbol. Never assume they are the same.
- Health Monitor: drift detection in depth
-
Response Contract: reading
errors/warnings - Configuration: every tunable