TrueNAS SCALE / Troubleshooting
TrueNAS SCALE SMB Share Exists but Client Access Is Denied
Confirm the share is reachable and the client authenticates as a Samba-enabled user, then separate the share ACL, the dataset (filesystem) ACL, the parent Traverse permission, and the share read-only and enumeration settings before any ACL change.
TrueNAS uses Samba to provide SMB services. The TrueNAS SCALE documentation states that the root user, TrueNAS built-in user accounts, and users without Samba Authentication enabled cannot access SMB shares. The documented symptom in this case is a permissions or access-denied result on a same-protocol request, not a missing share or a stopped service.[1][2]
The TrueNAS SCALE documentation describes two independent ACL levels for an SMB share: the share ACL (Edit Share ACL) which applies at the SMB share level, and the dataset or filesystem ACL (Edit Filesystem ACL) which applies at the share dataset level. The documentation requires the NFSv4 ACL type for SMB datasets and notes that for datasets with the NFSv4 ACL type, SMB clients automatically use access-based enumeration, which restricts directory listings to entries the client can read.[2][3]
Applicability
- Products
- TrueNAS SCALE
- Scope
- For a TrueNAS SCALE deployment where the SMB share is created, the SMB service is running, and the share is visible to the client, but a same-protocol access returns an access-denied or permissions result. The current TrueNAS SCALE stable documentation as published on the TrueNAS documentation hub on 2026-09-06 describes two separate ACL levels (share ACL and dataset or filesystem ACL), an NFSv4 ACL type recommended for SMB datasets, and a Traverse requirement on parent datasets. Verify the current release and exact menu labels in the deployment before making changes; this page does not cover an offline or unreachable NAS, an SMB1-only legacy client, an NFS share, a Time Machine-specific behavior, or an Active Directory bind failure as the primary symptom.[1][2][3]
- Last verified
Symptoms
- The SMB share is created, the SMB service is running, and the share is visible or browsable, but the client fails to read or write with an access-denied or permissions result. An offline or unreachable NAS, a stopped service, a missing share, a wrong-server name, or a wrong-password authentication failure is a different observation.[1][2]
Quick diagnosis
Check the share, the user, the dataset ACL, the parent path, and the share settings separately. Share-level and dataset-level permissions are independent.
Confirm the share exists and the SMB service is running
Inspect the Shares screen for the intended SMB share and the System Settings Services screen (or the equivalent current menu) for the SMB service state. The TrueNAS documentation states that when an SMB share is configured but not working or is in an error state, Active Directory cannot bind and TrueNAS cannot start the SMB service; a stopped or errored service needs its own diagnosis.[2]
Identify the authenticating user and confirm Samba Authentication is enabled
On the client, identify the exact user the SMB session uses. On TrueNAS, open Credentials, Users for the user account and confirm that SMB Access is selected; the documentation states that the user must be a non-root, non-built-in account with Samba Authentication enabled, and that root, TrueNAS built-in users, and users without Samba Authentication cannot access SMB shares.[2]
Confirm the share dataset uses the NFSv4 ACL type
Open Datasets, select the share dataset, and inspect the Permissions widget. The TrueNAS documentation states that datasets created with the SMB preset have an NFSv4 ACL type and that only NFSv4 ACLs should be used with SMB shares. A POSIX ACL on an SMB dataset is not the documented configuration for SMB.[3]
Do not change ACLs or the dataset before classification
Do not delete the ACL, set the dataset to a POSIX ACL, or apply a recursive ACL change to bypass the symptom. The TrueNAS documentation labels recursive ACL changes as destructive and recommends creating a ZFS snapshot of the dataset before changing the ACL type or modifying permissions. A change made before the failure is classified can make the recovery path longer.[3]
Interactive troubleshooter
Your answers stay in this browser tab. The tool does not connect to your systems or send diagnostic results.
Guided check / step 1
Safe diagnostic guidanceIs the SMB share created, the SMB service running, and the client able to reach the share?
Use the TrueNAS Shares screen and the System Settings Services screen (or the equivalent current menu). The TrueNAS documentation states that when an SMB share is configured but not working or is in an error state, Active Directory cannot bind and TrueNAS cannot start the SMB service.[2]
Read the complete diagnostic tree without using the controls
- Is the SMB share created, the SMB service running, and the client able to reach the share?
Use the TrueNAS Shares screen and the System Settings Services screen (or the equivalent current menu). The TrueNAS documentation states that when an SMB share is configured but not working or is in an error state, Active Directory cannot bind and TrueNAS cannot start the SMB service.[2]
- Yes, share and service are available → Is the client authenticating as a non-root user with Samba Authentication enabled?
- No, share or service is unavailable → Investigate the actual share or service state
- Cannot determine the share or service state → Investigate the actual share or service state
- Is the client authenticating as a non-root user with Samba Authentication enabled?
The TrueNAS documentation states that root, TrueNAS built-in users, and users without Samba Authentication enabled cannot access SMB shares. Open Credentials, Users and confirm SMB Access is selected for the authenticating user.[2]
- Yes, Samba-enabled non-root user → Is the authenticating user or group present in the dataset (filesystem) ACL?
- No, root or no Samba Authentication → Use a non-root, Samba-enabled user
- User record is unknown → Investigate the actual share or service state
- Is the authenticating user or group present in the dataset (filesystem) ACL?
Open Edit ACL on the share dataset. The TrueNAS documentation describes the share ACL and the dataset ACL as independent; a user present in the share ACL but absent from the dataset ACL is denied at the dataset level. The default ACL is restrictive and only grants access to the dataset owner and group.[2][3]
- Yes, present with the intended permission → If the share is nested, does each parent dataset grant Traverse to the user or group?
- No, the user or group is absent → Add the user and group ACE to the dataset ACL
- ACL contents are unclear → If the share is nested, does each parent dataset grant Traverse to the user or group?
- If the share is nested, does each parent dataset grant Traverse to the user or group?
Inspect each parent dataset's Permissions widget. The TrueNAS documentation states that for a nested share, each parent dataset in the path needs a Traverse ACE for the user and group; without Traverse, the user cannot reach the share dataset even when the share dataset's own ACL permits access.[2]
- Yes, Traverse is granted on each parent → Is Export Read-Only enabled on the share?
- No, Traverse is missing on a parent → Add a Traverse ACE on each parent dataset
- The share is not under a parent dataset → Is Export Read-Only enabled on the share?
- Parent layout is unclear → Is Export Read-Only enabled on the share?
- Is Export Read-Only enabled on the share?
The TrueNAS documentation describes Export Read-Only as prohibiting writes to the share. This is a separate setting from Access Based Share Enumeration. For datasets with the NFSv4 ACL type, access-based enumeration is automatic and cannot be disabled.[2]
- Yes, Export Read-Only is enabled → Clear Export Read-Only if writes are intended
- No, Export Read-Only is disabled → Review the share ACL and the dataset ACL independently
- Export Read-Only state is unclear → Review the share ACL and the dataset ACL independently
- Investigate the actual share or service state
Confirm that the share is created, the SMB service is running, and the client can reach the share. An offline or unreachable NAS, a stopped service, a missing share, a wrong-server name, a wrong-password authentication failure, an SMB1-only legacy client, or an Active Directory bind failure needs its own investigation.[2]
- Use a non-root, Samba-enabled user
Open Credentials, Users, select the authenticating user, enable SMB Access, and save. Use a non-root, non-built-in account for the client connection. The TrueNAS documentation states that root, TrueNAS built-in users, and users without Samba Authentication enabled cannot access SMB shares.[2]
- Add the user and group ACE to the dataset ACL
Open Edit ACL on the share dataset, add a new ACE for the user and the group with the intended permission, and save. The TrueNAS documentation describes the dataset ACL as independent from the share ACL. The default ACL is restrictive and only grants access to the dataset owner and group; modify the ACL to fit the use case.[2][3]
- Add a Traverse ACE on each parent dataset
For each parent dataset in the share path, open Edit ACL, add a new ACE for the user and the group with the Traverse permission, and save. The TrueNAS documentation states that without Traverse on the parent datasets, the user cannot reach the share dataset even when the share dataset's own ACL permits access.[2]
- Clear Export Read-Only if writes are intended
On the share, clear Export Read-Only if writes are intended and verify that the intended user can write after the change. The TrueNAS documentation states that Export Read-Only prohibits writes to the share. Access Based Share Enumeration is a separate setting; for datasets with the NFSv4 ACL type, access-based enumeration is automatic and cannot be disabled.[2]
- Review the share ACL and the dataset ACL independently
Open Edit Share ACL on the share and Edit ACL on the share dataset, and verify the user and group are present in both with the intended permissions. The TrueNAS documentation describes the share ACL and the dataset ACL as independent; the share ACL does not grant dataset-level access, and the dataset ACL does not set the share-level permission. A user present in only one of the two ACLs is denied when the request reaches the level that lacks the entry.[2][3]
Detailed diagnosis
1. Confirm the client user is a Samba-enabled non-root account
Compare the authenticating user with the TrueNAS user record. The TrueNAS documentation requires a non-root, non-built-in user with Samba Authentication enabled; root, TrueNAS built-in users, and users without Samba Authentication cannot access SMB shares. If the authenticating user does not match, leave this page and address the user record first.[2]
2. Inspect the dataset (filesystem) ACL for the authenticating user and group
Open Edit ACL on the share dataset and look for the user and group the client uses. The TrueNAS documentation describes the share ACL and the dataset ACL as independent; a user present in the share ACL but absent from the dataset ACL will still be denied at the dataset level. The default ACL is restrictive and only grants access to the dataset owner and group; modify the ACL to fit the use case.[2][3]
3. If the share is nested, inspect Traverse on each parent dataset
When the share dataset is under one or more parent datasets, inspect each parent's Permissions widget. The TrueNAS documentation states that for a nested share, each parent dataset in the path needs a Traverse ACE for the user and group; without Traverse, the user cannot reach the share dataset even when the share dataset's own ACL permits access.[2]
4. Inspect the share read-only and enumeration settings
On the share, inspect Export Read-Only, which the TrueNAS documentation describes as prohibiting writes to the share, and Access Based Share Enumeration, which restricts share visibility to users with read or write access. For datasets with the NFSv4 ACL type, the documentation states that access-based enumeration is automatic and cannot be disabled. A read-only setting can explain a write denial even when the dataset ACL permits the write.[2]
Supported scenarios
These observations narrow the next investigation; they do not establish a unique cause.
The client authenticates as a user that cannot access SMB shares
The TrueNAS documentation states that root, TrueNAS built-in users, and users without Samba Authentication enabled cannot access SMB shares, regardless of the share or dataset ACL.[2]
How to check: Open Credentials, Users, confirm SMB Access is selected, and use a non-root, non-built-in account with Samba Authentication enabled.[2]
The authenticating user or group is absent from the dataset (filesystem) ACL
The TrueNAS documentation describes the share ACL and the dataset ACL as independent. A user present in the share ACL but absent from the dataset ACL is denied at the dataset level, even when the share is exposed. The default dataset ACL is restrictive and only grants access to the dataset owner and group.[2][3]
How to check: Open Edit ACL on the share dataset and confirm whether the user and group ACE exists with the intended permission. The TrueNAS documentation describes the dataset ACL as separate from the share ACL; the share ACL alone is not sufficient.[2][3]
A parent dataset in the share path lacks Traverse for the user or group
The TrueNAS documentation states that for a nested share, each parent dataset in the path needs a Traverse ACE for the user and group. Without Traverse, the user cannot reach the share dataset even when the share dataset's own ACL permits access.[2]
How to check: Inspect each parent dataset's Permissions widget and confirm whether each parent grants Traverse to the user and group.[2]
Next actions and procedure boundaries
User account: enable Samba Authentication and use a non-root account
Open Credentials, Users, select the authenticating user, enable SMB Access, and save. Use a non-root, non-built-in account for the client connection; the TrueNAS documentation states that root, TrueNAS built-in users, and users without Samba Authentication enabled cannot access SMB shares. Do not set a POSIX-only user as the SMB client; the documentation requires Samba Authentication.[2]
Before changing anything
- Risk
- Enabling SMB Access on a user account is a user-account mutation; confirm the account is the intended SMB client before saving. This page does not change the password, delete the user, or modify any dataset or share ACL.[2]
- Safer check
- Confirm the authenticating user is the correct non-root, non-built-in account. Verify the current SMB Access state before changing it.[2]
- Expected result
- After enabling SMB Access, the user can authenticate to the SMB share. The share ACL, dataset ACL, and Traverse permissions are still independent boundaries that may also need review.[2]
- Backup / recovery access
- Record the current SMB Access state for the user before changing it. No ZFS snapshot is needed for a user-account change.[2]
- Rollback
- If the user should not have SMB access, clear SMB Access on the user account and save. This page does not supply a broader user-account rollback.[2]
Dataset ACL: add the user and group ACE
On the share dataset, open Edit ACL, add a new ACE for the user and the group with the intended permission, and save. The TrueNAS documentation describes the dataset ACL as separate from the share ACL; the share ACL alone is not sufficient. The default ACL is restrictive and only grants access to the dataset owner and group; modify the ACL to fit the use case.[2][3]
Before changing anything
- Risk
- ACL changes are configuration changes; recursive ACL changes are documented as destructive. An ACL change that removes a needed ACE will lock the intended user or the admin out of the dataset.[3]
- Safer check
- Record the current dataset ACL entries, the dataset owner, and the owner group. Confirm the share dataset uses the NFSv4 ACL type; the documentation requires NFSv4 ACLs for SMB shares. Do not switch the dataset to a POSIX ACL as a workaround.[3]
- Expected result
- After the ACL change, the intended user can read or write as expected, and the documented boundary (root, built-in, no Samba) is still enforced. A successful single ACE does not prove that other permissions are preserved.[2][3]
- Backup / recovery access
- Create a ZFS snapshot of the share dataset before any ACL change; the documentation recommends a snapshot before changing the ACL type or modifying permissions. Record the current ACL entries and the change you are about to make.[3]
- Rollback
- If the intended user is locked out, restore the recorded prior ACL entries. If a recursive change was applied, restore the dataset from the pre-change ZFS snapshot before further investigation.[3]
Parent datasets: add a Traverse ACE for the user and group
For each parent dataset in the share path, open Edit ACL, add a new ACE for the user and the group with the Traverse permission, and save. The TrueNAS documentation states that without Traverse on the parent datasets, the user cannot reach the share dataset even when the share dataset's own ACL permits access.[2]
Before changing anything
- Risk
- Traverse changes to parent datasets affect every share and every client that traverses the same parent path. An incorrect change on a parent dataset can affect unrelated shares and services.[2]
- Safer check
- Identify every share and service that traverses the parent dataset. Record the current parent ACL entries. Confirm the parent uses the NFSv4 ACL type; the documentation requires NFSv4 ACLs for SMB shares.[2][3]
- Expected result
- After the change, the intended user reaches the share dataset and the other shares and services that traverse the same parent still work as before.[2]
- Backup / recovery access
- Create a ZFS snapshot of the parent dataset before any ACL change. Record the current ACL entries and the change you are about to make.[3]
- Rollback
- If an unrelated share or service is affected, restore the recorded prior ACL entries on the parent dataset. If a recursive change was applied, restore the parent from the pre-change ZFS snapshot before further investigation.[3]
Share write access: clear Export Read-Only if writes are intended
On the share, inspect Export Read-Only, which the TrueNAS documentation describes as prohibiting writes to the share. Clear Export Read-Only if writes are intended and verify that the intended user can write after the change. This is a separate setting from Access Based Share Enumeration; the documentation states that for datasets with the NFSv4 ACL type, access-based enumeration is automatic and cannot be disabled.[2]
Before changing anything
- Risk
- Clearing Export Read-Only allows write access to the share for all users who have write permission in the dataset ACL. This changes the share-level access boundary; confirm the dataset ACL and share ACL already grant the intended write permissions before clearing the setting.[2]
- Safer check
- Record the current Export Read-Only setting and the current dataset ACL and share ACL. Confirm the intended user already has write permission at the dataset level before allowing writes at the share level.[2][3]
- Expected result
- After clearing Export Read-Only, the intended user can write to the share. Users who lack write permission in the dataset ACL are still denied. A successful write by the intended user does not prove that unrelated users are unaffected.[2]
- Backup / recovery access
- Record the current Export Read-Only state and the current share and dataset ACLs before changing the setting.[2]
- Rollback
- If writes should be prohibited again, re-enable Export Read-Only on the share and save.[2]
Share ACL vs dataset ACL: review both independently
The TrueNAS documentation describes the share ACL (Edit Share ACL) as applying at the SMB share level only, and the dataset ACL as applying at the share dataset level. The two are independent; the share ACL does not grant dataset-level access, and the dataset ACL does not set the share-level permission. A user present in only one of the two ACLs is denied when the request reaches the level that lacks the entry.[2][3]
If the access boundary cannot be classified: preserve the evidence
Record the authenticating user and group, the current dataset ACL, the parent datasets' ACLs, the share ACL, the share read-only and enumeration settings, and the SMB service state. Send the sanitized evidence to the operator or maintainer; the TrueNAS documentation does not describe a generic access-denied remedy that bypasses the ACL levels.[2]
Before any separately scoped recursive ACL or dataset type change
Planning boundary only. The operator must consider the current ACL on the share dataset and on every parent dataset, the current NFSv4 or POSIX ACL type, and the other shares and services that depend on the same path. This page does not change the dataset ACL type, apply a recursive ACL to bypass the symptom, delete the ACL, or set a chmod-style blanket grant.[3]
Before changing anything
- Risk
- Changing the dataset ACL type, applying a recursive ACL, or deleting the ACL is documented as destructive and can lock the intended user, the admin, or unrelated services out of the dataset or its parent path.[3]
- Safer check
- First record the current dataset ACL, the parent ACLs, the ACL type, and the share ACL. Confirm the share dataset uses the NFSv4 ACL type; the documentation requires NFSv4 ACLs for SMB shares.[3]
- Expected result
- A later owner-approved change must leave the intended user able to reach the share, must not weaken the protection on parent datasets, and must not affect unrelated shares and services. A successful write after a destructive change does not prove that other permissions are preserved.[3]
- Backup / recovery access
- Create a ZFS snapshot of the dataset and of every affected parent dataset before any ACL type change, recursive ACL change, or ACL deletion. The documentation recommends a snapshot before changing the ACL type or modifying permissions.[3]
- Rollback
- If the intended user is locked out or an unrelated share or service is affected, restore the dataset and parent datasets from the pre-change ZFS snapshots before further investigation. If only a non-recursive ACL was changed, restore the recorded prior ACL entries first.[3]
Warnings and boundaries
Sources
Links were reviewed on 2026-09-06. Reachability and automated validation do not replace editorial verification of each claim.
- Windows Shares (SMB)
TrueNAS / iXsystems · Tier A · accessed 2026-09-06 - Adding and Managing SMB Shares
TrueNAS / iXsystems · Tier A · accessed 2026-09-06 - Configuring ACL Permissions
TrueNAS / iXsystems · Tier A · accessed 2026-09-06