Skip to main content

​
Troubleshooting Access Issues

This guide helps you diagnose and fix common access control problems.

​
Common Issues

​
Issue: User Can’t See Documents They Should

Symptoms: User asks a question but gets “I don’t have information about that” even though relevant documents exist. Diagnostic Steps:
  1. Check user’s roles 
    console.log('User roles:', JSON.stringify(userRoles));
// Are the expected roles present?
  2. Check document’s ACL
    • What aclRoles were set when uploading?
    • Does any role match?
  3. Verify role matching 
    User roles: ["employee", "all-staff"]
Document ACL: ["hr"]

Match? NO - user needs "hr" role
Solutions:
  • Add the missing role to the user’s roles array
  • Add a role the user has to the document’s ACL
  • Re-upload the document with corrected ACL

​
Issue: User Sees Documents They Shouldn’t

Symptoms: AI responses include information from restricted documents. Diagnostic Steps:
  1. Check if document has ACL 
    Document uploaded without aclRoles = visible to everyone
  2. Check for overly broad roles 
    // Are you accidentally giving admin/superuser roles?
roles = ['admin', 'all-access', ...]; // Too broad!
  3. Verify role assignment logic 
    // Bug: Always including 'hr' regardless of department
const roles = ['all-staff', 'hr']; // Wrong!
Solutions:
  • Add appropriate ACL to unrestricted documents
  • Review and fix role assignment logic
  • Remove overly permissive roles from users

​
Issue: Inconsistent Access

Symptoms: User can see some documents but not others with the same intended access level. Diagnostic Steps:
  1. Audit ACLs across documents 
    doc1.pdf: aclRoles = ["hr"]
doc2.pdf: aclRoles = ["HR"]      // Case mismatch!
doc3.pdf: aclRoles = ["h-r"]     // Typo!
  2. Check role naming consistency
    • Are you using the same role names everywhere?
    • Case matters: hr ≠ HR
Solutions:
  • Standardize role names (recommend lowercase)
  • Re-upload documents with corrected ACLs
  • Create a role name registry/enum

​
Debugging Checklist

Use this checklist when troubleshooting: 
□ Print the exact roles being sent
□ Verify roles are JSON-formatted correctly
□ Check for case sensitivity issues
□ Confirm document was uploaded with expected ACL
□ Test with a known-working role combination
□ Check if document upload succeeded (status: Indexed)

​
Debug Logging

Add logging to your integration: 
async function askWithLogging(orgId, userId, roles, question) {
  console.log('=== DocBit AI Request Debug ===');
  console.log('Org ID:', orgId);
  console.log('User ID:', userId);
  console.log('Roles:', JSON.stringify(roles));
  console.log('Question:', question);
  
  try {
    const response = await DocBit AIClient.chat({
      headers: {
        'X-External-Org-Id': orgId,
        'X-External-User-Id': userId,
        'X-External-Roles': JSON.stringify(roles)
      },
      body: { message: question }
    });
    
    console.log('Citations:', response.citations?.length || 0);
    console.log('Confidence:', response.confidence);
    
    return response;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
    throw error;
  }
}

​
Testing Access

​
Test with Different Roles

async function testAccess(question) {
  const testCases = [
    { roles: ['employee'], expected: 'limited' },
    { roles: ['hr'], expected: 'hr-docs' },
    { roles: ['hr', 'manager'], expected: 'hr-and-manager-docs' },
    { roles: ['admin'], expected: 'all-docs' }
  ];
  
  for (const test of testCases) {
    console.log(`\nTesting with roles: ${test.roles}`);
    const response = await askQuestion('test-org', 'test-user', test.roles, question);
    console.log('Got citations:', response.citations?.map(c => c.documentTitle));
  }
}

​
Verify Document Upload

After uploading, verify the document was indexed: 
// Check document status
const doc = await getDocument(documentId);
console.log('Status:', doc.status); // Should be 'Indexed'
console.log('ACL Roles:', doc.aclRoles);

​
Common Mistakes

​
1. Roles Not JSON-Encoded

// Wrong - not valid JSON
headers['X-External-Roles'] = "hr, manager";

// Correct
headers['X-External-Roles'] = JSON.stringify(['hr', 'manager']);
// Or: '["hr", "manager"]'

​
2. Empty Roles Array

// Wrong - will be rejected
headers['X-External-Roles'] = '[]';

// Correct - at least one role required
headers['X-External-Roles'] = '["employee"]';

​
3. Client-Side Role Assignment

// WRONG - never trust client-provided roles
app.post('/ask', (req, res) => {
  const roles = req.body.roles; // User could pass anything!
});

// CORRECT - derive roles server-side
app.post('/ask', authMiddleware, (req, res) => {
  const roles = getRolesFromUser(req.user);
});

​
4. Forgetting Base Role

// Might miss company-wide documents
const roles = [user.department]; // Only department role

// Better - include base role
const roles = ['all-staff', user.department];

​
Getting Help

If you’re still having issues:
  1. Gather debug info:
    • Exact roles being sent
    • Document IDs and their ACLs
    • API response (including any error messages)
  2. Reproduce consistently:
    • Create a minimal test case
    • Document steps to reproduce
  3. Contact support:

​
FAQ

Documents take a few seconds to index. Check the document status - it should be “Indexed” before it appears in search results.
Currently, you need to track ACLs on your side. We’re working on an API to retrieve document metadata including ACLs.
Upload documents without ACLs (they’re public to the org), or ensure the user has all the roles used in document ACLs.
Currently, you need to delete and re-upload. We’re working on an update API.