Troubleshooting Potfile Issues¶

Potfile Preset Job Not Created¶

Symptoms¶

• Potfile wordlist exists in Resources → Wordlists
• No "Potfile Run" job in Admin → Preset Jobs
• Logs show "No binary versions found" messages

Cause¶

The potfile preset job requires a hashcat binary to be uploaded. On fresh installations, no binaries exist, so the preset job cannot be created (it needs a binary version pattern to resolve).

Solution¶

1. Upload a hashcat binary via Admin → Binary Management
2. Wait for verification to complete
3. Check Admin → Preset Jobs - "Potfile Run" should appear within 5-10 seconds
4. If not visible after 30 seconds, restart the backend service

Prevention¶

Always upload a hashcat binary as the first step after installation. This is documented in the Quick Start and First Crack guides.

Verification¶

Check system logs for confirmation:

docker logs krakenhashes 2>&1 | grep -i "potfile preset job"

You should see one of these messages: - "Successfully created pot-file preset job with ID: [uuid]" - Success - "Waiting for binary versions to be added before creating pot-file preset job" - Still waiting - "Found existing pot-file preset job with ID" - Already exists

Technical Details¶

The potfile system initializes in two stages:

1. Potfile Wordlist Creation (always succeeds):
2. Creates /data/krakenhashes/wordlists/custom/potfile.txt
3. Adds wordlist entry to database with is_potfile = true

4. Sets system setting potfile_wordlist_id

5. Preset Job Creation (requires binary):

6. Attempts to create "Potfile Run" preset job
7. Requires at least one active binary for pattern resolution
8. If no binaries exist, starts background monitor
9. Monitor checks every 5 seconds for binary availability
10. Creates preset job once binary is uploaded

Potfile Not Being Updated¶

Symptoms¶

• Cracked passwords not appearing in potfile
• Potfile size not increasing
• Staging table has entries but potfile is unchanged

Common Causes and Solutions¶

1. Potfile Disabled
2. Check: SELECT value FROM system_settings WHERE key = 'potfile_enabled';
3. Fix: UPDATE system_settings SET value = 'true' WHERE key = 'potfile_enabled';

4. Restart backend service

5. Background Worker Stopped

6. Check logs: docker logs krakenhashes 2>&1 | grep "pot-file service"
7. Look for: "Pot-file service started" vs error messages

8. Fix: Restart backend service

9. Staging Table Processing Issues

10. Check staging count: SELECT COUNT(*) FROM potfile_staging;
11. Check staging by destination: SELECT client_id, exclude_from_global, exclude_from_client, COUNT(*) FROM potfile_staging GROUP BY client_id, exclude_from_global, exclude_from_client;
12. Check for old entries: SELECT COUNT(*) FROM potfile_staging WHERE created_at < NOW() - INTERVAL '1 hour';

13. If stuck, manually clear: DELETE FROM potfile_staging WHERE created_at < NOW() - INTERVAL '1 hour';

14. File Permission Issues

15. Check file exists: ls -la /data/krakenhashes/wordlists/custom/potfile.txt
16. Check permissions allow writing
17. Fix: chmod 644 /data/krakenhashes/wordlists/custom/potfile.txt

Potfile Wordlist Shows Wrong Count¶

Symptoms¶

• Wordlist entry shows incorrect word count
• Keyspace calculations are wrong
• Jobs using potfile have incorrect progress

Solution¶

The system should automatically update counts during batch processing. If not:

1. Check recent batch processing:

   SELECT * FROM wordlists WHERE is_potfile = true;
   

2. Manually trigger recount (requires backend restart):

   UPDATE wordlists 
   SET word_count = (SELECT COUNT(*) FROM potfile_lines),
       updated_at = NOW()
   WHERE is_potfile = true;
   

3. Update preset job keyspace:

   UPDATE preset_jobs 
   SET keyspace = (SELECT word_count FROM wordlists WHERE is_potfile = true)
   WHERE name = 'Potfile Run';
   

Duplicate Passwords in Potfile¶

Symptoms¶

• Same password appears multiple times
• File size larger than expected
• Performance degradation

Causes¶

• Manual editing of potfile while system is running
• Database/filesystem sync issues
• Processing errors

Solution¶

1. Stop the backend service
2. Back up the current potfile
3. Remove duplicates:

   sort -u /data/krakenhashes/wordlists/custom/potfile.txt > /tmp/potfile_clean.txt
   mv /tmp/potfile_clean.txt /data/krakenhashes/wordlists/custom/potfile.txt
   

4. Update database:

   UPDATE wordlists 
   SET word_count = (SELECT COUNT(*) FROM potfile_lines),
       file_size = pg_stat_file('/data/krakenhashes/wordlists/custom/potfile.txt').size,
       updated_at = NOW()
   WHERE is_potfile = true;
   

5. Restart backend service

Monitor Not Creating Preset Job¶

Symptoms¶

• Binary uploaded but preset job still missing
• Logs show monitor is running but not creating job
• System seems stuck waiting

Debugging Steps¶

1. Check if monitor is running:

   docker logs krakenhashes 2>&1 | grep "monitor for binary versions"
   

2. Check for any binaries:

   SELECT id, binary_type, is_active, verification_status 
   FROM binary_versions;
   

3. Check system settings:

   SELECT * FROM system_settings 
   WHERE key IN ('potfile_wordlist_id', 'potfile_preset_job_id');
   

4. Force retry by clearing preset job ID:

   UPDATE system_settings 
   SET value = NULL 
   WHERE key = 'potfile_preset_job_id';
   

   Then restart backend

Manual Creation (Last Resort)¶

If automatic creation fails, manually create the preset job:

-- Get the wordlist ID
SELECT id FROM wordlists WHERE is_potfile = true;

-- Get a binary version ID
SELECT id FROM binary_versions WHERE is_active = true LIMIT 1;

-- Create the preset job
INSERT INTO preset_jobs (
    id, name, wordlist_ids, rule_ids, attack_mode,
    priority, chunk_size_seconds, status_updates_enabled,
    allow_high_priority_override, binary_version, keyspace
) VALUES (
    gen_random_uuid(),
    'Potfile Run',
    '["WORDLIST_ID"]'::jsonb,  -- Replace WORDLIST_ID
    '[]'::jsonb,
    0,  -- Dictionary attack
    1000,  -- Max priority
    1200,  -- 20 minute chunks
    true,
    true,
    'default',  -- Uses default binary pattern
    1  -- Initial keyspace
);

-- Update system settings with the new ID
UPDATE system_settings 
SET value = (SELECT id::text FROM preset_jobs WHERE name = 'Potfile Run')
WHERE key = 'potfile_preset_job_id';

Client Potfile Issues¶

Client Potfile Not Being Created¶

Symptoms: - Client has cracked hashes but no potfile exists - wordlists/clients/{uuid}/ directory doesn't exist - client_potfiles table has no entry for the client

Common Causes and Solutions:

1. Client potfiles disabled system-wide
2. Check: SELECT value FROM system_settings WHERE key = 'client_potfiles_enabled';
3. Fix: UPDATE system_settings SET value = 'true' WHERE key = 'client_potfiles_enabled';

4. Restart backend service

5. Client excluded from client potfile

6. Check: SELECT exclude_from_client_potfile FROM clients WHERE id = 'client-uuid';

7. Fix: UPDATE clients SET exclude_from_client_potfile = false WHERE id = 'client-uuid';

8. All hashlists excluded from client potfile

9. Check: SELECT name, exclude_from_client_potfile FROM hashlists WHERE client_id = 'client-uuid';

10. Fix: UPDATE hashlists SET exclude_from_client_potfile = false WHERE id = 'hashlist-id';

11. File permission issues

12. Check: ls -la /data/krakenhashes/wordlists/clients/
13. Fix: Ensure the backend process can create directories and files in the wordlists/clients/ path

Client Potfile Shows Wrong Count¶

Symptoms: - client_potfiles.line_count doesn't match actual file line count - Job using client potfile has incorrect keyspace

Solution:

-- Check metadata vs actual file
SELECT client_id, line_count, file_size, updated_at FROM client_potfiles;

Restart the backend to force bloom filter reload and metadata refresh.

Passwords Not Removed on Hashlist Delete¶

Symptoms: - Deleted a hashlist with "remove from client potfile" checked - Client potfile still contains the passwords

Debugging Steps: 1. Check backend logs for regeneration errors: docker logs krakenhashes 2>&1 | grep -i "regenerat" 2. Verify client setting: SELECT remove_from_client_potfile_on_hashlist_delete FROM clients WHERE id = 'uuid'; 3. Check system default: SELECT value FROM system_settings WHERE key = 'remove_from_client_potfile_on_hashlist_delete_default'; 4. Verify the deletion request included the removal flag in the JSON body

Bloom Filter Memory Issues¶

Symptoms: - High memory usage from backend process - Many active clients with large potfiles

Solution: - The system limits client bloom filters to 50 (maxClientBlooms). Each uses approximately 1.2 MB. - Restart the backend to clear all cached bloom filters - Consider reducing the number of active clients with potfiles if memory is constrained

Best Practices¶

1. Always upload a binary first during initial setup
2. Don't manually edit the potfile while the system is running
3. Monitor staging table size - large backlogs indicate processing issues
4. Check logs regularly for potfile-related errors
5. Keep batch intervals reasonable (30-60 seconds recommended)
6. Archive old potfiles if they grow beyond 1GB

Related Documentation¶

• Potfile Management Guide
• Client Management Guide
• Binary Management