Where the Agent Can Read Files From: Drive Letters, Shares, Cloud Folders, Mac and Linux

Connector setup · Files and folders

Where the Agent can read files from

The Agent opens your files as a background service, not as you. This page shows which locations work, and walks you through fixing the ones that do not.

5 to 15 minutes Windows, Mac and Linux Files stay where they are

Why a path that works for you can fail for the Agent

You can open the file, so why can’t the Agent? The Agent runs in the background as a service, starts before anyone signs in, and has its own identity on the computer. Anything that exists only for a signed-in person, such as a mapped drive letter, a OneDrive file that is only in the cloud, or your home folder on Linux, does not exist for the Agent.

This applies to every connector that reads a file or a folder: Microsoft Access, SQLite, DuckDB, and the folder connectors (CSV, Excel, Parquet, JSONL and SQLite folders, File System, and the log folders).

Who opens the file on each kind of computer

Does this location work?

Find where your file or folder is, then follow the link in the last column if it needs a fix.

If your file is on a drive letter like S: or Z:

A drive letter like S: that points at a server is a shortcut that exists only while you are signed in. The Agent starts before anyone signs in, so it has never seen that shortcut. The real location behind the letter, a network path that starts with two backslashes like \\FILESERVER\Shared, works for both of you. What you see when you use the letter anyway:

• Microsoft Access, SQLite, DuckDB: the file is not found. The Browse dialog leaves the letter out and says Mapped drives (like Z:) are not shown; a typed path fails with File does not exist, Directory not found: S:\, or SQLite database file not found / DuckDB database file not found followed by the path.
• Folder connectors (File Set): an amber note under Root folders says the letter may be a mapped network drive, and the test refuses the folder by name: it says the path is on the mapped network drive S: and asks for a UNC path instead.

1. See what the letter points to

   On the computer where you see the S: drive, open File Explorer (the yellow folder icon on the taskbar, or press the Windows key and E together) and click This PC in the list on the left. Scroll to the heading Network locations. Each mapped drive is listed there with its real path in its name, in this shape: Shared (\\FILESERVER) (S:). The server name is inside the brackets, FILESERVER; the share name comes before them, Shared. Write both down.

   If the name has been changed to something like Accounts drive (S:) and the brackets are missing, use one of the other two ways:

   From the address bar. Open the folder that holds your file. Click once in the empty space of the address bar at the top of File Explorer; it changes from This PC › Shared (S:) › Accounts to a typed path. If the path starts with two backslashes, that is the one you want: select it all and copy it. If it still shows S:\Accounts, use the next way.

   From Command Prompt. Click Start, type cmd, and click Command Prompt (a normal click; no administrator needed). In the black window, type the line below and press Enter:

   Type this, then press Enter

   net use

   A short table appears. Find the row whose Local column says S:; its Remote column is the network path, for example \\FILESERVER\Shared. Write that down and close the window. If the table says There are no entries in the list, the letter is not a network drive; it is a real disk in that computer, and if that computer is the Agent’s, the letter works as it is.

2. Build the full path

   Take the network path from step 1 and add everything that came after the drive letter:

   What you see	What to type instead
   S:\Accounts\orders.accdb	\\FILESERVER\Shared\Accounts\orders.accdb
   S:\Exports\daily (a folder)	\\FILESERVER\Shared\Exports\daily
   Z:\shop.db	\\NAS\data\shop.db

   Only the letter part changes; folders and file names stay exactly as they were.

3. Put it in the Portal

   For one file (Access, SQLite, DuckDB): type or paste the full path into the Database File Path box. Or click Browse, click in the box at the bottom that reads Type a folder or full file path on the agent, type the share part, \\FILESERVER\Shared, and press Enter. The folder opens through the Agent and you can click down to the file.

   For a folder connector: type the path into Root folders, one folder per line. Or click Browse, then the Network path button, type \\FILESERVER\Shared in the box and click Connect. The share opens through the Agent and you can click down to the folder.

4. Test it

   Click Test connection. Connected (or, for a folder connector, a green result naming how many files it can see) means you are done; click Save.

   If the message mentions access denied or denied, the Agent found the server but was not let in. Carry on with the next section.

If the network share asks for a username and password

When the Agent opens a share, it does not use your name and password. On Windows it arrives as the computer itself. How you let it in depends on the computer the Agent runs on:

Windows: type the network path, then store the login

Use the network path, like \\FILESERVER\Shared\Accounts\orders.accdb, never a drive letter. Then give the connector the login for that server:

• Microsoft Access, SQLite, DuckDB: as soon as Database File Path starts with two backslashes, a small chip appears under it that reads Service identity. Click it, fill in the box as in step 3 below, and click Save; the chip then shows the account name. If the path check says access is denied, a button Enter credentials for \\FILESERVER appears next to the chip and opens the same box.
• Folder connectors: follow steps A below.

When you test or run a query, the Agent signs in to that server with the login and reads the real file there, live; nothing is copied. Windows allows one sign-in per file server, so each Agent uses one account per server: every connector on that Agent that reads the same server must use the same login. A second connector with a different account is refused with Another connector on this agent already signs in to \\fileserver as and the first account’s name. After a refused password, the Agent waits a minute before it tries that same login again, so the account is not locked out; saving a corrected password tries again straight away.

A. Folder connectors on Windows: give the share a login

1. Get a read-only account for the share

   Ask whoever runs the server for a username and password that can read the folder. An account that can only read is best; the Portal says so too: Use a least-privilege, read-only account.

2. Add the folder by its network path

   In the connector form, under Root folders, click Add folder from the agent…, then the Network path button. Type the share, for example \\FILESERVER\Shared, and click Connect.

   If the share turns the Agent away, a box opens by itself, titled Credentials for \\FILESERVER. If it does not open, or you added the folder by typing, find the folder’s row in Root folders: its Credential column says Service identity. Click the small pencil button on that row (hover text: Edit the credential for \\FILESERVER) and the same box opens.

3. Type the login and save

   Fill in Username and Password. Domain is optional: type the company domain (for example CORP) if your username belongs to one, or leave it blank for an account made on the server itself. Click Save. The box closes, and the folder’s Credential column no longer says Service identity; it names the account you entered.

   One login covers every folder on that server: the box says One identity per file server.

4. Test the folder

   Click the play button on the folder’s row (hover text: Test this folder from the agent machine). The Status column changes to reachable. If it says credentials invalid, the server turned the login down: check the username, the password and the Domain, and try again. If it says denied, point at the word to read the Agent’s message. Usually the login works but that account may not read the folder; ask for read permission on it. If the message starts Another connector on this agent already signs in to or Windows already holds a sign-in to, a different account already signs in to that server from the Agent’s computer, and the message says what to do.

B. Windows, no login to give: let the computer in, or move the Agent

Without a stored login, the Agent opens the file as its own identity: the computer. If you cannot get an account for the share, or would rather not store one, pick the fix that matches your network:

1. Simplest: put the Agent where the file is

   If you may install programs on the computer or server that holds the file, install the Agent there. The file becomes a local path like D:\Data\orders.accdb. Then add the connector on that Agent. This works on every kind of network.

2. Company network with a domain: grant the computer account

   On a domain, the server sees the Agent’s computer as its computer account: the computer’s name with a dollar sign. To find the name, on the Agent’s computer click Start, type cmd, open Command Prompt, type the line below and press Enter:

   Type this, then press Enter

   hostname

   One word appears, for example RECEPTION. Ask whoever runs the server to give RECEPTION$ read permission on the shared folder: both the share permission and the folder’s security permission. Then click Test connection again.

3. Home or small-office network: copy the file, or move the Agent

   Without a domain, the server does not know the Agent’s computer at all, and current versions of Windows refuse the old “guest” workaround by default (Microsoft explains why), so we do not recommend opening the share to everyone. Use step 1, keep a copy of the file in a folder on the Agent’s computer, or ask for an account on the share and store it as above.

Linux: mount the share first, then use the mount path

On Linux the Agent does not use a share login stored in the Portal, and its service is not allowed to mount anything itself. In the connector form, the chip under the path reads Mounted on the agent instead of offering a login. An administrator mounts the share once, in a folder under /mnt or /media; not under /home or /run/user, which the service cannot see (why).

The steps use the share \\FILESERVER\Shared. If the test already says is not mounted on this Linux agent, the same two mount lines are in that message with your server and share filled in, and you can copy them from there.

1. Install the mount tools

   In a terminal on the Agent’s computer, use the line for your system. If the tools are already there, you see a line saying so.

   Ubuntu or Debian

   sudo apt-get install -y cifs-utils nfs-common

   Red Hat, Rocky, Alma, Fedora or Amazon Linux

   sudo dnf install -y cifs-utils nfs-utils

2. Windows or Samba share: put the login in a file only root can read

   Skip this step for an NFS share. Make the folder, then open a new file named after the server, in lower case:

   Type each line, then press Enter

   sudo mkdir -p /etc/querystreams
   sudo nano /etc/querystreams/fileserver.cred

   Type these three lines with the share account’s details. Leave out the domain line for an account made on the server itself. To save, press Ctrl and O together, then Enter; press Ctrl and X to close.

   Type these lines, with your own details

   username=svc-reader
   password=the-share-password
   domain=CORP

   Then make the file belong to root, readable by root only:

   Type each line, then press Enter

   sudo chown root:root /etc/querystreams/fileserver.cred
   sudo chmod 600 /etc/querystreams/fileserver.cred

3. Mount the share

   Make the folder, then run the mount line for your kind of share. Any folder name works; this one is the name the Agent’s own message uses.

   Windows or Samba share (SMB)

   sudo mkdir -p /mnt/fileserver-shared
   sudo mount -t cifs //fileserver/Shared /mnt/fileserver-shared -o credentials=/etc/querystreams/fileserver.cred,ro,vers=3.0,uid=querystreams

   NFS share

   sudo mkdir -p /mnt/fileserver-shared
   sudo mount -t nfs fileserver:/Shared /mnt/fileserver-shared

   The prompt comes back with no message. ro mounts the share read-only, which is all the Agent needs. If your NFS server exports the folder under a longer path, such as /exports/Shared, put that path after the colon; the Agent still recognises it when the path starts or ends with the share name.

   A mount made this way lasts until the computer restarts. To keep it, ask whoever looks after the server to add it to /etc/fstab.

4. Point the connector at the mounted folder and test

   Swap the server and share part of the path for the mount folder, and turn the backslashes into forward slashes:

   Network path	What to type on Linux
   \\FILESERVER\Shared\Accounts\shop.db	/mnt/fileserver-shared/Accounts/shop.db
   \\FILESERVER\Shared\Exports\daily (a folder)	/mnt/fileserver-shared/Exports/daily

   Click Test connection. You can also keep the \\FILESERVER\Shared path in any connector instead: once the share is mounted, the Agent finds the mount and reads through it, as long as the mount names the server the same way (both by name, or both by the same IP address).

Mac: mount the share from Terminal, then use the mount path

On a Mac the Agent does not use a share login stored in the Portal either. Mount the share from Terminal with sudo (a root shell), so the Agent’s service can see it, in a folder under /Volumes. If the test already says is not mounted on this macOS agent, the mount lines are in that message with your server and share filled in.

1. Mount the share

   Open Terminal (press Command and Space, type Terminal, press Return). Make the folder, then run the mount line for your kind of share. For SMB, put the share account’s username in place of USER. Type your Mac password when sudo asks; for SMB, macOS then asks for the share account’s password.

   Windows or Samba share (SMB)

   sudo mkdir -p /Volumes/fileserver-shared
   sudo mount -t smbfs //USER@fileserver/Shared /Volumes/fileserver-shared

   NFS share

   sudo mkdir -p /Volumes/fileserver-shared
   sudo mount -t nfs fileserver:/Shared /Volumes/fileserver-shared

   The prompt comes back with no message. As on Linux, the mount lasts until the Mac restarts.

2. Point the connector at the mounted folder and test

   Type the path under /Volumes, for example /Volumes/fileserver-shared/Accounts/shop.db, and click Test connection. You can also keep the \\FILESERVER\Shared path in any connector, as on Linux.

If your file is in OneDrive, Google Drive or Dropbox

These apps save space by leaving files in the cloud until you open them. File Explorer still lists the file, but there is nothing on the disk for the Agent to read. A blue cloud icon next to a file means it is online only. The fix is to tell the app to keep the folder on the computer all the time.

1. Find the folder on the Agent’s computer

   On the computer that runs the Agent, open File Explorer and go to the folder that holds your file (or, for a folder connector, the folder itself). Do this for the whole folder, not just one file, so new files are kept too.

2. Right-click the folder and keep it on the computer

   Right-click the folder, then choose the option for your app. On Windows 11, if you do not see it, click Show more options at the bottom of the menu first.

   OneDrive

   Always keep on this device

   Google Drive for desktop

   Offline access → Available offline (on a Mac, just Available offline)

   Dropbox

   Make available offline

   The files download in the background. Large folders can take a while.

3. Wait for the green tick

   When the download finishes, the folder and its files show a green tick. For OneDrive it is a solid green circle with a white check mark. A plain green check without the filled circle means the file is on the computer for now but OneDrive may send it back to the cloud later, so use step 2 rather than just opening the file.

4. Use the path, and test

   Use the folder’s normal path, for example C:\Users\Sam\OneDrive\Accounts\orders.accdb. Click Test connection. For a folder connector, files that were online only are skipped without a message, so if the test finds fewer files than you expect, check step 3 again.

Google Drive as a drive letter (G:). In its default Stream files mode, Google Drive for desktop shows up as its own drive letter, and the Agent refuses it with a message that starts This file is on a cloud drive in streaming mode, which is not supported. Either make the folder Available offline (step 2) and keep using the G: path, or switch Google Drive to keep a full copy on the computer: open Google Drive for desktop, open Settings → Preferences, click Folders from Drive on the left, and under My Drive syncing options choose Mirror files (Google’s steps). The Agent’s message says “Mirror mode” for OneDrive too; OneDrive has no such setting, and Always keep on this device is the OneDrive answer.

Linux: if the file is in your home folder

The Agent’s service is set up with a standard Linux safety setting, ProtectHome=true, that makes /home, /root and /run/user look empty to it. A file at /home/sam/data/shop.db is right there for you and simply not there for the Agent: the test says File does not exist, Directory not found or SQLite database file not found, and a folder connector shows the folder as missing. Nothing is wrong with the file. Pick one of the two fixes.

Fix 1 (recommended): move the data out of /home

1. Make a folder outside /home

   In a terminal on the Agent’s computer, type the line below and press Enter. Type your password when sudo asks; nothing shows while you type it, which is normal.

   Type this, then press Enter

   sudo mkdir -p /srv/data

   The prompt comes back with no message. That means it worked.

2. Move (or copy) the file or folder there

   Change the path to your own, then press Enter. Use cp -r instead of mv if you want to leave the original where it is.

   Type this, then press Enter

   sudo mv /home/sam/data/shop.db /srv/data/

3. Point the connector at the new path and test

   In the Portal, change the path to /srv/data/shop.db (or the folder, /srv/data) and click Test connection. You should see Connected. If whichever program writes the file has to keep writing it, point that program at the new place too, or use Fix 2.

Fix 2: let the service read home folders

This changes one setting on the Agent’s service so it can read (never write) inside /home. It stays in place when the Agent updates itself.

1. Open the service’s override file

   Type this, then press Enter

   sudo systemctl edit querystreams-agent

   A text editor opens in the terminal (usually nano), with some lines starting with #. Near the top there is a gap between two comment lines that says to put your changes there.

2. Type these two lines in the gap

   Type these two lines

   [Service]
   ProtectHome=read-only

   To save in nano, press Ctrl and O together, then Enter; then press Ctrl and X to close. The prompt comes back.

   Want the Agent to see only one folder rather than every home folder? Use these lines instead, with your own folder: ProtectHome=tmpfs on one line and BindReadOnlyPaths=/home/sam/data on the next.

3. Restart the Agent

   Type this, then press Enter

   sudo systemctl restart querystreams-agent

   The prompt comes back with no message. In the Portal the Agent shows Offline for a few seconds, then Online again. Click Test connection.

   If it now says Access denied instead of “not found”, your Agent was installed with reduced permissions; the next section explains the setfacl line to add.

Linux: if /var/log or the Docker log folders say Access denied

A standard install of agent 2.6.6 or newer reads every log on the computer, including /var/log and /var/lib/docker/containers, through a read-only permission called CAP_DAC_READ_SEARCH. If the Browse dialog says Access denied to: /var/lib/docker (or another folder), the Agent adds a sentence that names which of four causes it is. Find the sentence below and do what its row says.

1. To restart the Agent with its current settings

   Type each line and press Enter after it. If you are removing the reduced-permission file, run the first line too; otherwise start at the second.

   Type each line, then press Enter

   sudo rm /etc/systemd/system/querystreams-agent.service.d/minimal-permissions.conf
   sudo systemctl daemon-reload
   sudo systemctl restart querystreams-agent

   Each line returns to the prompt with no message. The Agent shows Online again in the Portal within a minute; open Browse again.

2. Or keep reduced permissions and grant one folder

   First make sure the setfacl tool is installed. Use the line for your system:

   Ubuntu or Debian

   sudo apt-get install -y acl

   Red Hat, Rocky, Alma, Fedora or Amazon Linux

   sudo dnf install -y acl

   If it is already there, you see a line saying so. Then grant read access to the folder, putting your folder in place of /var/log/nginx. The second line covers files created later:

   Type each line, then press Enter

   sudo setfacl -R -m u:querystreams:rX /var/log/nginx
   sudo setfacl -d -m u:querystreams:rX /var/log/nginx

3. For Docker logs, grant three things

   Docker’s own folder has to let the Agent pass through as well as read the containers folder. These are the exact lines the Portal shows:

   Type each line, then press Enter

   sudo setfacl -m u:querystreams:x /var/lib/docker
   sudo setfacl -R -m u:querystreams:rX /var/lib/docker/containers
   sudo setfacl -d -m u:querystreams:rX /var/lib/docker/containers

   Each returns with no message. Open Browse again in the Portal; the folder now lists its contents. No restart is needed for this one.

Mac: if the file is in Desktop, Documents or Downloads

macOS keeps background programs out of your Desktop, Documents and Downloads folders until you allow them. The Agent then shows Access denied to: and the folder, followed by macOS protects this folder (Full Disk Access) and these same steps in short. You give the permission once, on the Mac that runs the Agent; it carries over when the Agent updates itself.

1. Open Full Disk Access

   Click the Apple menu (top left), then System Settings. In the sidebar click Privacy & Security. On the right, scroll down if needed and click Full Disk Access. A list of apps appears, each with a switch.

2. Click the + button

   Click the + button under the list. macOS asks for your Mac password or Touch ID; give it. A window for choosing a file opens, showing your Applications folder.

3. Go to the Agent’s program

   The Agent is not in Applications, so jump straight to it: press Command, Shift and G together. A small box opens to type a location. Type the line below exactly, including the space in Service Client, and press Return:

   Type this, then press Return

   /usr/local/querystreams/agent/Service Client

   The window jumps to the agent folder with Service Client selected. Click Open.

4. Check the switch is on

   Service Client now appears in the list. Make sure its switch is on. If it is not in the list, go back to step 2 and check the line you typed in step 3, space included.

5. Restart the Agent

   macOS only applies the permission when the Agent starts. Open Terminal (press Command and Space, type Terminal, press Return), type the line below and press Return. Type your Mac password when asked; nothing shows while you type it, which is normal.

   Type this, then press Return

   sudo launchctl kickstart -k system/com.querystreams.agent

   The prompt comes back with no message. In the Portal the Agent is Online again within a minute. Open Browse or click Test connection again.

If another program has the file open

Most of the time this is fine: the Agent only reads, and reads alongside the program that owns the file. When it is not fine, it depends on the connector:

1. Microsoft Access

   Keep Read-Only Mode on (it is on by default). If the test still says The Access database file is locked by another process, Access opened the file exclusively. In Access, click File, Options, Client Settings, and under Advanced set Default open mode to Shared, then close and reopen the database. Full steps on the Access page.

2. SQLite

   On Windows, picking a file another program holds shows This file is in use by another application. Enable ‘Read-Only (Immutable)’ mode to connect safely. That tick box is on by default. It tells the Agent the file will not change while it reads, so it skips the file’s locks.

   When that is safe: a file that is only replaced now and then (a nightly copy, an export, an archive). When it is not: a file a program is writing to right now, such as a till, an app’s live database, or anything with a -wal file next to it. SQLite’s own documentation warns that reading a changing file this way can give wrong answers. For a live file, untick Read-Only (Immutable), or point the connector at a copy the program makes on a schedule.

3. DuckDB

   DuckDB lets one program write to a file at a time, and while it does, nobody else can open it, not even to read. If the test fails with a message about a lock, close the file in the other program (DuckDB, Python, DBeaver), or have that program open it read-only, then click Test again. The Agent retries briefly on its own before it gives up.

4. Excel workbooks in an Excel Folder connector

   While a workbook is open, Excel puts a hidden lock file beside it whose name starts with ~$. Folder connectors skip those automatically; you do not need to do anything. If a real workbook shows Locked by another program in the test’s file list, save and close it in Excel; the next scan picks it up.

What the message means

Find the words you see, then follow the link.

Next: set up your connector

• Set up the Microsoft Access connector
• SQLite to Microsoft Excel
• DuckDB to Microsoft Excel
• Combine a folder of CSV files into one table
• Query Docker container logs with SQL

Related guides

• Install the Agent on Windows
• Install the Agent on a Mac
• Install the Agent on Linux
• All guides