Tinyfacade Troubleshoot

Should show package:com.tinyfacade. If not, install the APK first.

Models — No Models Found or Load Fails

Symptoms: getAvailableModels() returns empty list, onModelLoaded(false) fires, "no models" in logs.

Checklist

1. Where to put GGUF files TinyFacade scans two locations:

   • /sdcard/Android/data/com.tinyfacade/files/ (app's external files)
   • /sdcard/Download/ (Downloads folder)

   Push via adb:

   adb push my-model.gguf /sdcard/Android/data/com.tinyfacade/files/
   

2. File must have .gguf extension Only files ending in .gguf are discovered.

3. Storage permissions On some devices, you may need to grant TinyFacade storage permissions manually in Settings.

4. Model too large If onModelLoaded(false) fires, the model may be too large for device RAM. Try a smaller quantization (Q4_K_M instead of Q8_0).

5. Load another model first If a model is already loaded, call releaseModel() before loading a different one.

Performance — Slow Inference

Symptoms: Very slow token generation, low tokens/second, UI lag during generation.

Checklist

1. Use GPU layers Set n_gpu_layers to 99 (or higher) to offload to GPU:

   params.putInt("n_gpu_layers", 99)
   

2. Reduce context size Lower n_ctx if you don't need large context:

   params.putInt("n_ctx", 1024)  // instead of 2048
   

3. Use smaller models Recommended for mobile:

   • Q4_K_M quantization (best speed/quality balance)
   • 1B-3B parameter models for real-time use
   • 7B models work but are slower

4. Reduce max tokens

   params.putInt("n_predict", 256)  // instead of 512
   

5. Check device temperature Thermal throttling significantly reduces inference speed. Let the device cool down.

6. Only one model at a time Loading multiple models consumes all available memory. Release one before loading another.

Tools — Tool Calling Not Working

Symptoms: Model doesn't call tools, tool results not incorporated, tools return errors.

Checklist

1. Enable tools in params Must set enable_tools to true:

   params.putBoolean("enable_tools", true)
   

2. Model must support tool calling Not all GGUF models support tool calling. TinyFacade uses the model's chat template to format tool prompts. Models that work well:

   • Command-R / Aya (Cohere format)
   • Models with Jinja chat templates that include tool sections

3. Message format Messages must be JSON with role and content fields:

   [{"role": "user", "content": "What time is it?"}]
   

4. Tool calling is transparent Your app never sees the tool loop. If tools are enabled:

   • The model generates internally
   • TinyFacade detects <tool_call> tags, executes the tool, feeds results back
   • Your onToken() only receives the final natural-language response

   If you're not getting tool results, the model may not be generating tool calls — try a prompt that clearly needs a tool ("What's the current time?" for get_current_time).

5. Custom tool registration Verify registration succeeded:

   val ok = service.registerTool(definition, action)
   // ok should be true
   

   Then verify it appears:

   val tools = service.availableTools  // JSON string
   

6. HTTP tool timeouts If a custom HTTP tool times out, increase timeout_ms or check the URL.

Signing — Certificate Mismatch

Symptoms: bindService() returns false silently, SecurityException in logcat.

How signing works

TinyFacade declares a signature-level permission:

<permission
    android:name="com.tinyfacade.permission.USE_INFERENCE"
    android:protectionLevel="signature" />

This means only apps signed with the exact same certificate can bind to the service.

Development (debug builds)

Both apps must use the same debug.keystore. Options:

1. Copy TinyFacade's keystore to your project:

   cp /path/to/TinyFacade/android/app/debug.keystore ./
   

2. Point your signing config at it:

   signingConfigs {
       getByName("debug") {
           storeFile = file("debug.keystore")
           storePassword = "android"
           keyAlias = "androiddebugkey"
           keyPassword = "android"
       }
   }
   

Production (release builds)

For release, you must:

1. Sign TinyFacade with your release keystore
2. Sign your client app with the same release keystore
3. Or distribute TinyFacade signed with a shared keystore

Verify signatures match

# Check TinyFacade's signature
adb shell dumpsys package com.tinyfacade | grep -A5 "signatures"

# Check your app's signature
adb shell dumpsys package com.example.myapp | grep -A5 "signatures"

Both should show the same certificate fingerprint.