'python' is not recognized (Windows) or command not found: python (Mac)
Python is not installed, or the terminal cannot find it. On Windows, run the Python installer again, choose Modify, and make sure Add Python to environment variables is ticked, then open a new terminal. On a Mac, type python3 instead of python.
'pip' is not recognized
Use python -m pip instead of pip, as the setup guide does.
'jupyter' is not recognized
Use python -m notebook to start Jupyter.
ERROR: file:///... does not appear to be a Python project
The terminal is not in the pubmed-stream folder. cd into the folder that holds pyproject.toml, then install again.
ModuleNotFoundError: No module named 'tutorial_utils'
The notebook was opened from outside the tutorials folder. Start Jupyter from the pubmed-stream folder and open the notebook inside tutorials.
ModuleNotFoundError: No module named 'matplotlib' (or pandas, networkx)
The tutorial tools are not installed. Run python -m pip install -e ".[tutorials]" in the pubmed-stream folder.
A command-line search with a quoted phrase finds unrelated papers or fails, on Windows
Windows PowerShell drops the inner double quotes of '"gut microbiota"[Title]', and Command Prompt does not understand single quotes. In Windows PowerShell, put a backslash before each inner quote: '\"gut microbiota\"[Title] AND frailty[Title/Abstract]'. In Command Prompt, use double quotes outside: "\"gut microbiota\"[Title] AND frailty[Title/Abstract]". The notebooks avoid the problem.
Jupyter opens a page in the browser, then stops working
The terminal that started it was closed. Start it again with python -m notebook.
NameError: name 'QUERY' is not defined (or another setting)
The cells were run out of order, or the settings cell was skipped. Run the whole notebook from the top: Run > Run All Cells.
Changed settings, but the results did not change
Earlier results were still in memory. Choose Kernel > Restart Kernel and Run All Cells (in Colab, Runtime > Restart session and run all).
A cell shows [*] for many minutes
It is waiting for NCBI. Large downloads take a few minutes; an API key makes them three times faster. If nothing changes for ten minutes, choose Kernel > Interrupt Kernel and run the cell again.
Pink boxes with 429 Client Error: Too Many Requests
NCBI asked pubmed-stream to slow down, and it waited and retried. This is normal and harmless unless the cell fails. To avoid it, add an API key, and don't run several notebooks at once.
SyntaxError in the settings cell
A quote or bracket is missing. Text goes between straight quotes, "like this". A search that contains double quotes goes between single quotes: '"gut microbiota"[Title]'.
ConnectionError, SSLError or Max retries exceeded
The computer cannot reach NCBI. Check the internet connection. On a university or hospital network, a firewall may block it: try another network, or ask IT whether a proxy is needed. They can tell you the value to put in an HTTPS_PROXY environment variable.
Searches and downloads are slow, or 429 Too Many Requests
Without an NCBI API key, NCBI allows 3 requests a second instead of 10. Get a free key and save it with pubmed-stream init --ncbi-api-key YOUR-KEY; init also asks for it while none is saved.
NCBI rejected the API key
The saved key has a typo or was revoked, and pubmed-stream continues without it. Create a key in your NCBI account settings and save it again with pubmed-stream init --ncbi-api-key YOUR-KEY.
A search finds 0 articles
Check the spelling, quotes and brackets. Paste the search into PMC's website to test it; its Advanced search builds field tags for you. A MeSH heading must be spelled exactly as in the MeSH browser.
A search finds tens of thousands of articles
It is too broad. Put the main concept in the title with [Title], add AND terms, or use MeSH headings. Tutorial 2 shows how, step by step.
Many articles are unavailable
Their publishers do not allow full-text download. Add AND "open access"[filter] to the search, or accept that they will be missing.
Only recent papers were downloaded
Searches return the newest matches first. Raise the number of articles, add a date range such as AND 2010:2018[pdat], or add a key paper to bring in the older literature.
Excel opened the CSV with the wrong encoding. The tutorials save CSVs that Excel reads correctly; for other CSVs, use Data > From Text/CSV in Excel and choose UTF-8.
Colab asks before running notebooks from GitHub. Choose Run anyway.
Results or downloads disappeared
Colab deletes everything when the session ends. Run the notebook again, and save what you want to keep with the notebook's last cell or File > Download.
The zip file did not download
The browser blocked it. Allow downloads from colab.research.google.com, then run the last cell again.
You opened the folder above the graph. Open the kg_<topic> folder itself, the one that holds PubMed Stream.md.
The graph view is a crowded ball of dots
Most dots are cited papers without a note. Switch on Existing files only under Filters in the graph settings, filter further with path:papers, and spread it with the Forces sliders. See the Obsidian guide.
The graph has no colours
Colours are set when the graph is first built, and only if the vault has none yet. Add them yourself under Groups in the graph settings.
Clicking a link creates an empty note
The paper is cited but was not downloaded or added as a stub. Its PubMed ID is in the link's name. Delete the empty note if you don't need it.
Notes I wrote disappeared after a rebuild
They were inside the generated block, between the %% pubmed-stream:start and %% pubmed-stream:end lines. Write below the end line; see write your own notes.
| Command line interface is not enabled from obsidian | Obsidian's own command line is off. In Obsidian, open Settings > General, switch on Command line interface, follow the prompt, and open a new terminal. |
| pubmed-stream open says Obsidian does not know the graph | Obsidian opens only folders it already knows. Add the kg_<topic> folder once with Open folder as vault; after that, open works. |
The MCP server, pubmed-stream mcp, did not start or is not connected. Type /mcp: Claude Code shows the server and any error, and Codex lists the tools. With pubmed-stream init, start the assistant in the folder where you ran it, or run it there again; in Claude Code, approve the server if asked. With the plugin, check that claude plugin list or codex plugin list shows pubmed-stream, and install it as in tutorial 7 if not; if it is listed, uv is probably not installed, and the plugin needs it to fetch pubmed-stream. Restart the assistant afterwards.
The plugin's tools are older than pubmed-stream's newest release
Each plugin version runs the pubmed-stream release of the same number. Update it as in tutorial 7, and restart the assistant.
The assistant lists every pubmed-stream tool twice
The folder was set up with pubmed-stream init before you installed the plugin, so the plugin and the folder each start a server. Run pubmed-stream init in the folder again: with the plugin installed, it removes the folder's own server.
init works, but the server fails to start later
The settings point to the Python that ran init. If you moved or removed that Python environment, run pubmed-stream init again from the one you use now.
Codex ignores the model I set in the research folder
Codex 0.163 does not read a folder's model setting. Choose it with /model during the session, start with codex -m <model>, or set model in the config.toml of the .codex folder in your home folder.
Codex stops at download or build_knowledge_graph
Tools that save files need your approval. Approve them when asked; in codex exec, add --approve-for-me.
The assistant cites a paper you cannot find
Ask which tool output it read the paper in. Open https://pubmed.ncbi.nlm.nih.gov/<PMID>/; if the PMID is not among the downloads (pubmed-stream list publications --id <PMID>), do not rely on the claim.