# Troubleshooting

Common errors and how to fix them.

## `NoDOIError` — Paper has no DOI

**When:** Calling `axm-bib pdf` or `BibPipeline.download_pdf()` with a paper that has no DOI.

**Solution:** Use `axm-bib search` to find the paper's DOI. If it only has an arXiv ID, use the arXiv DOI format:

```bash
# arXiv papers have DOIs like 10.48550/arXiv.<id>
axm-bib pdf 10.48550/arXiv.1706.03762
```

---

## `CrossRefError` — CrossRef API failure

**When:** Resolving a DOI via `axm-bib resolve` or `BibPipeline.resolve_bibtex()`.

**Causes:**

- Invalid DOI format
- CrossRef API temporarily unavailable
- Network connectivity issues

**Solution:**

1. Verify the DOI is valid (e.g. `10.1145/363235.363259`)
2. Try again — CrossRef outages are usually brief
3. Check your network connection

---

## `SemanticScholarError` — Search API failure

**When:** Running `axm-bib search` or `BibPipeline.search()`.

**Causes:**

- Rate limit exceeded (~100 requests per 5 minutes on public tier)
- Semantic Scholar API maintenance

**Solution:**

1. Wait a few minutes and retry
2. Set an API key for higher rate limits:

```bash
export S2_API_KEY="your-api-key"
```

!!! tip "Automatic fallback"
    When Semantic Scholar fails, `axm-bib` automatically falls back to CrossRef,
    then DBLP for search. You'll still get results, but without abstracts or citation counts.

---

## `DBLPError` — DBLP API failure

**When:** DBLP is used as a search fallback or when fetching native BibTeX.

**Causes:**

- DBLP API temporarily unavailable
- Network connectivity issues

**Solution:**

1. Wait a few minutes and retry
2. DBLP is the last search fallback — if it fails, the search returns no results

---

## `OpenReviewError` — OpenReview API failure

**When:** Searching or browsing papers via `OpenReviewClient`.

**Causes:**

- OpenReview API temporarily unavailable
- Invalid venue ID format
- Forum ID not found

**Solution:**

1. Verify the venue ID format (e.g. `NeurIPS.cc/2024/Conference`)
2. Check that the forum ID exists on [openreview.net](https://openreview.net)
3. Wait and retry — OpenReview outages are usually brief

---

## `ArXivError` — arXiv API failure

**When:** Fetching BibTeX or searching via `ArXivClient`.

**Causes:**

- arXiv API temporarily unavailable
- Invalid or non-existent arXiv ID
- Rate limit exceeded (1 request per 3 seconds)

**Solution:**

1. Verify the arXiv ID format (e.g. `1706.03762`, `math/0102101`)
2. `ArXivClient` enforces rate limiting automatically — if you see timeout errors, wait and retry
3. Check [arxiv.org status](https://status.arxiv.org) for outages

---

## `OpenAlexError` — OpenAlex API failure

**When:** Searching or looking up works via `OpenAlexClient`.

**Causes:**

- OpenAlex API temporarily unavailable
- Invalid OpenAlex work ID

**Solution:**

1. Verify the OpenAlex ID format (e.g. `W2741809807`)
2. Check [OpenAlex status](https://status.openalex.org) for outages
3. Set `email` when creating `OpenAlexClient` for polite API access

---

## `HALError` — HAL API failure

**When:** Searching or fetching BibTeX via `HALClient`.

**Causes:**

- HAL API temporarily unavailable
- Invalid HAL ID format

**Solution:**

1. Verify the HAL ID format (e.g. `hal-01234567`)
2. Check [HAL status](https://status.archives-ouvertes.fr) for outages
3. HAL uses a Solr backend — complex queries may need escaping

---

## `UnpaywallError` — OA lookup failure

**When:** Downloading a PDF via `axm-bib pdf`.

**Causes:**

- Email not configured (required by Unpaywall API)
- Unpaywall API temporarily unavailable

**Solution:**

Set your email:

```bash
export UNPAYWALL_EMAIL="user@example.com"
```

Or let `axm-bib` prompt you on first use — the value is saved to `~/.config/axm-bib/config.toml`.

---

## "Not open access — no PDF available"

**When:** The paper exists but has no open-access version.

**Why:** The paper is behind a paywall, and no OA copy exists on arXiv, PubMed Central, or the publisher's site.

**What you can do:**

1. Check your institution's library for access
2. Look for a preprint on the author's website
3. Use `axm-bib resolve` to at least get the BibTeX entry

---

## Network timeouts

**When:** Any command that calls an external API.

**Cause:** Slow network or API response times.

**What happens:** All `httpx`-based clients use `request_with_retry`, which automatically retries on transient errors (429, 500, 502, 503) and network failures (`httpx.TransportError`) with exponential backoff. After exhausting retries, structured exceptions are raised: `RateLimitError` (429) or `APIUnavailable` (502/503/504). Both inherit from `AXMBibError`, so you can catch them broadly or precisely.

**Solution:**

- If retries are exhausted, check your internet connection
- APIs may be slow during peak hours — retry later
- If behind a proxy, ensure `httpx` is configured (via `HTTP_PROXY` / `HTTPS_PROXY` env vars)
- Retry logs appear at `WARNING` level — check logs to see which API is failing

---

## Figure extraction warnings

**When:** Running `axm-bib pdf` or `axm-bib extract` — some figures may be skipped.

**Cause:** Some PDFs contain images in unsupported formats (CMYK, exotic ICC profiles, corrupted image data).

**What happens:** `axm-bib` skips unreadable figures and continues extraction. The Markdown content and other figures are not affected.

!!! info "This is expected"
    Figure extraction is best-effort. The number of extracted figures
    is reported in the output — compare with the PDF to verify.
